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1 Overview and Goals 

The Returns on the Web (ROW) project is an XML OnLine Tool that will provide a Merchant with UPS 
reverse logistics services at a Consumer level over the Internet. The returns market is expected to grow 
12% annually in response to a) A shift in buying behavior (increased online shopping); b) Increased 
demands for Merchant customer service; b) Increased need for shippers to recoup salvage value from 
returns. 

The business model of primary interest involves three actors: 

Merchant - UPS' customer who wishes to facilitate returns using the Internet. These merchants will likely 

be both Dot Com and "clicks and mortar" retail merchants. 
Consumer - The Merchant's customer who wishes to return something purchased from the Merchant. 
Vendor - The destination of the returned goods. This may be a repair depot, the original manufacturer of 

the goods, or the Merchant itself. All of these possibilities are lumped under the term Vendor. 

UPS return services in this release will be in three forms: 

PRL - Print Return Label 

PRL XML - The return label is returned to the Merchant in the XML response 
PRL Email - An email with a link to the Label Recovery servlet is sent to the Consumer. When 
selected the link passes an encrypted parameter that drives the servlet to generate the label, which 
is presented in the Consumer's browser. 

1 A/3A - One Attempt or Three Attempt Pickup. The label is printed in the UPS center a 
picks the package up from the consumer. 

The goals of the architecture will be: 

• Integrate with customer (Merchant and Vendor) systems 

• Minimize external implementer effort to accelerate adoption and market penetration 

• Make effective, efficient use of UPS systems and resources 

• To use familiar models and design patterns 

Two XML OnLine Tools will be created: 

1 . Returns on the Web - An XML Tool to allow the Merchant to request one of the above services plus 
notification emails. 

2. Label Recovery - A new XML Tool will allow the Merchant to recover previously generated labels. 
This tool will be created from scratch and call other service components, UIS and Tracking. The 
servlet supporting this tool will also support email delivery. 

Returns on the Web (the marketing name for ROW) has been prototyped by PRD and is currently deployed 
by several customers. We have studied the prototype carefully. 

UPS Returns on the Web will not be offered through any other channel, including www. ups. com 




the driver 
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1.1 Assumptions 

1. Access to ROW will be on a special contract basis only; billing changes will not be required beyond 
those supplied in support of the UIS February Initiative. 

2. The UPS Internet shipping team in Maryland will provide support for the "Local Print", "1 Attempt", 
and "3 Attempt" services for February, 2001. 

3. FOSS (Label Generation Group) supports return Labels. 

4. ROW will support only US50 origins and destinations. 

5. The documentation, SDKs, and How-to's will be delivered via ups.com, 

6. Developer profile for SDK will be medium to high capability Java developer at a Fortune 1000 
company. This profile will be revised to a broader audience in the future. 

7. ROW will only be offered as an XML Tool. 

8. ROW services will not be available through the XML OnLine Shipping Tool. 

9. The Merchant will be the only user of the XML Tool. The Consumer and Vendor will not contact UPS 
through this tool. 

10. The ROW XML Tool will not be backward compatible with the Harbinger/Tandata Pilot. 

11. Normal Internet email delivery latency will not impact perceived product value. 

12. The current ship notification email will not be employed. 

13. This is a tool: there is no user interface for this project. 

1.2 Risks 

Integration into Merchant systems may require Merchant process redesign at numerous levels that this 
product does not address. 
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2 Architecture 

2. 1 High Level Application Architecture 

There will be two XML Tools: 

1 .. Returns on the Web - Using the XML Shipping Tool source code as a base, this new tool will call on 

the same UIS component as the Shipping Tool for returns services. 
2. Label Recovery - A new tool, Label Recovery will allow Merchants to obtain previously generated 

labels in case of failed delivery or loss by Consumers. 



The diagram below shows the major parts of the system. Some of the parts depicted will not be 
development targets for this project (the Merchant Process, for instance). 




SNE Server 

UPS Center 
1A/3A Label Print 



Vendor 

Figure 1: High Level Application Architecture 



The basic process is this: 

1. Consumer, requests a return from the Merchant 

2. Merchant requests a label from UPS 

Or 

Merchant requests 1 Attempt or 3 Attempt Pickup from UPS 

3. UPS delivers label to Consumer, via web browser (encrypted link is emailed). 

Or 

Merchant delivers label to Consumer. 

4. UPS sends various emails as requested, including Return Notification to Vendor 
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2.2 Data Center Physical/Logical Schematic 




Web 
Server 



Local Director 



Web 
Server 



Web 
Server 



App Server 
UIS - IMS 



SNE Server 




Web 
Server 



Figure 2: Data Center Physical/Logical Schematic 
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2.3 Deliverables 



Deliverable 


Location 


Memory or Disk 


ROW XML OnLine Tool Servlet 


Web Tier App Servers 


36 - 96 Mb 


Label Recovery XML OnLine Tool Servlet 


Web Tier App Servers 


36-96 Mb 


OLT Email Program 


Web Tier App Servers 




ROW SDK 


ec.ups.com 


3.5 Mb Disk 


Documentation and How-to 


ec.ups.com 


1 Mb Disk 



2.4 Execution Environment, App Servers 

JRE 1.1.6 (R4) and 1.1.8 
Sapphire 

XML4J version 2.0.15 

2.5 SNE Required Changes 

The XOLT email component will reside on the SNE servers (galileo.unix.us.ups.com and 
galileo2.unix.us.ups.com). It will connect with the same UPS Exchange Server as the Ship Notification 
process uses. 

To send email and handle bounced email, the XOLT Email Component will need a mailbox similar to the 
"pkginfo" mailbox used by Ship Notification. 

The XOLT Email Component will create logs that must be included in the log sweep process. 
The XOLT Email Component will require the following be installed on the SNE servers: 
JRE 1.1.8 

XML4J version 2.0.15 ■ 

JavaMail 1.2 http:// www, j avasoft.com/products/javamaiiyindex. html 

JAF 1.0.1 http://www.iavasoft.con^eans/glasgow/iaf.htrnl 




UIS App Server 



SNE Servers 



ROW Servlets 




Sockets 




OLT Email 
Application 



<3 



SMTP 



Top Level Email 
Server 



Figure 3: Email Infrastructure Overview 
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2.6 Process Scenarios 

In general, the Merchant process requests a return service from UPS by submitting an XML request to the 
UPS ROW XML OnLine Tool. The tool servlet calls on UIS to create the label and upload PLD. 
Subsequently, based on the Merchant request, one of the following occurs: 

1 . The PRL label is returned in the XML response document or a link is emailed to the Consumer. The 
Consumer either carries the package to an UPS drop-off location on includes the package with others 
being picked up by the driver. 

2. The 1 -Attempt/3 -Attempt request is forwarded by the back end systems to the centers where the label 
is printed. The driver attaches the label when the package is picked up. 

3. Also based on the Merchant request, emails may also be sent to the vendor (Return Notification), or 
the Consumer (Pickup Notification). 



2.6.1 Scenario: PRL XML 

The Consumer contacts the Merchant and requests a return. The Merchant decides to handle the task of 
passing the return label to the Consumer and forwards the request via the XML ROW Tool to UPS. UPS 
returns the label to the Merchant via XML. At the request of the Merchant, the XML ROW Tool servlet 
sends a Return Notification email to the Vendor. It is expected that this scenario will occur in less than 5% 
of the cases. 



Qpngumer 



Merchant 



UPS 



Consumer 
Requests 
Return 



XML 



ReturnRequest 



Vendor 



Label Returned 
by Merchant 



Label Returned 
via XML 
Response 



Return 
Notification 
Email 



Figure 4: XML PRL Scenario 
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2.6.2 Scenario: PRL Email 

The Consumer contacts the Merchant and requests a return. The Merchant decides to ask UPS to send a 
return label via email to the Consumer and forwards the request via the XML ROW Tool to UPS. UPS 
confirms the request via XML and emails to the Consumer an encrypted link to a servlet that will generate 
the label. At the request of the Merchant, the XML ROW Tool servlet sends a Return Notification Email to 
the Vendor. 



Consumer 



Consumer 
Requests 
Return 




Label Link Emailed to Consumer 



Consumer clicks on link 
to request label 



Servlet displays label in browser 
window 



Vendor 



Return 
Notification 

Email 
(Optional) 



Figure 5: PRL Email Scenario 
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2.6.3 Scenario: 1A/3A 

The Consumer contacts the Merchant and requests a return. The Merchant decides that UPS 1 Attempt or 
UPS 3 Attempt service is appropriate and forwards the request via the XML ROW Tool to UPS. UPS 
confirms the request via XML. At the request of the Merchant the XML ROW Tool, servlet sends a Return 
Notification Email to the Vendor and a Pickup Notification Email to the Consumer. 



Cpnsymer 




Merchant 




UPS 




UPS Center 




Vendor 



Consumer 
Requests 
Return 



lt 



a 



XML 



ReturnRequest 



XML confirmation 



Pickup Notification Email 
(Optional) 



Print 1A/3A 



Label 



tl 



Return Notification Email 
(Optional) 



Driver picks up shipment 

Figure 6: 1 A/3A Scenario 
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2.6.4 Scenario: Label Recovery, XML 

On occasion a customer will lose the label and call the Merchant to ask for another. The Merchant requests 
a duplicate label from UPS using the ROW XML Tool. 



Copsupier 



Merchant 



UPS 



Consumer Requests 
Replacement Label 



Merchant transmits label 
to Consumer 



XML Label Recovery 
Request 



XML Label Response 



Figure 7: Label Recovery, XML 
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2.6.5 Scenario: Label Recovery, Email 

Alternatively, the Merchant may elect to send the link to the recovered label via email. 



Consumer 



Merchant 



UPS 



Consumer Requests 
Replacement Label 



XML Label Recovery 
Request 



XML Label Recovery 
Confirmed 



UPS Emails lifik to Consumer 



Consumer [clicks on link 



UPS presents) label in browser 



Figure 8: Label Recovery, Email 
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3 Components 

Four separate elements will require enhancement or original development: 

1 . XML tools servlets, ROW and Label Recovery 

2. UIS and downstream back-end systems 

3. ROW SDK 

4. XML OnLine Tools Email Component 



• Both of these tools will be protected by Licensing and Access. The IMS tool name will be "Returns on 
the Web". 

• Both of the servlets will use SSL for all processing, including label delivery. 

• Cookies will not be employed 



Component 




Implementation 


ROW XML OnLine Tool Servlet 




Java, JDK 1.1.6 and 1.1.8 


Label Recovery XML OnLine Tool Servlet 




Java, JDK 1.1.6 and 1.1.8 


OLT Email Program 




Java, JDK 1.1.6 and 1.1.8 


ROW SDK 




Java, JDK 1.1.6 and 1.1.8 
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3.1 Servlet, ReturnRequest 

The primary functionality of ROW XML OnLine Tool is rendered through UIS. There are many common 
between the Shipping and ROW servlets. 



The Shipping and ROW XML OnLine Tools will use the same DTDs. 

With the exception of the emails, all of the services will be requested through UIS. 

The RMA number will be specifically identified in the request and assigned to the first reference number. 



3.2 Servlet, Label Recovery 



The Label Recovery servlet must serve two functions: 1) handle the XML Tool Label Recovery 
Request/Response and 2) deliver the label to a web browser on demand. 



XML Tool LabelRecovery Request/Response 

Should the Merchant wish to retrieve the label (usually due to delivery failure or customer loss), the Label 
Recovery XML Tool will allow the Merchant to request a previously generated returns label by tracking 
number or reference number. All requests are subject to the following limitations: 

1 . Label must be have been generated in the last 30 days 

2. No physical scan in the tracking response 

3. Returns labels only 

4. Request must have singular result. (A reference number track can potentially yield multiple results if 
the Merchant cycles their RA numbers more frequently than UPS purges its databases.) 

The process is as follows: 

1 . Obtain tracking data to get PLD ID and check for a physical scan 

2. Call on PLD Replay to recover PLD detail 
3 . Call on UIS to generate label 

Label Delivery 



If the Merchant chooses email label delivery, the email will contain a link to the Label Recovery servlet. 
The link will also include an encrypted reference that will allow the servlet to recover the label and display 
it properly sized in the browser window. This approach will bypass numerous problems encountered when 
the label is included as an attachment in the email. 



When invoked by the link in the email, the Label Recovery servlet will adopt the behavior of an HTML 
servlet. 



A Label Delivery request will vet in the same way as a Label Recovery request. 

The single required parameter would be appended to the URL. It will consist of the following items 
concatenated into a string (in this order): 

7 characters of year and Julian date the label was generated (yyyyjjj) 

The tracking number of the label 

Locality (country code/language pair) 

The IMS registration ID of the Merchant 
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This string will be triple DES encrypted and URL encoded. The date and DES encryption will increase the 
randomness of the parameter string to make ROW less vulnerable to an iteration attack. The Label 
Recovery servlet will decode and decrypt the string, extract the 1Z, and recover the label using the process 
described. Static HTML will be used to display the properly sized label in the browser so that it can be 
directly printed. No interaction with the web server will be supported. 

If the label is unavailable or the request is invalid, static HTML with the error message will be displayed. 
The locality information will be used to present the error message in the appropriate language. 

This will require design of an HTML page for this purpose. 

3.3 ROW SDK 

In order to satisfy the requirement for the request process to be "very streamlined", a customer-side SDK 
will be provided. Decoupling UPS from the customer will be maintained by ensuring that the ROW XML 
documents are always backward compatible. The SDK will be deployed on the ec website only. 

Java classes will be provided that present to the customer the same design pattern as is found in the AV 
SDK. Internally the classes will implement the controller/adapter pattern. Classes implementing congruent 
interfaces in ASP capable VB are anticipated in future releases. 

The SDK objects will have getters and setters that the client developer can use to set up their request. 
Some limited range checks will be performed. To head off deployment issues, no business rules will be 
implemented in the SDK. The SDK Request object will construct the XML request, submit it to UPS 
HTTPS and return a Response object. The Request object will handle all SSL and Base64 issues. Sta 
including error codes and description, and the label (as a .gif) will be in the Response object. 

The ROW SDK will not contain source code or be capable of handling all possible networking issues 
although some proxy issues will be handled. 
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3.4 XOLT Email 

Email is becoming more important to the web applications and the XML Online Tools. In addition to mail 
transmission, XOLT Email will provide delivery that is more robust than standard Internet email and 
provide a basis for future improvements in email services. This program will be designed to handle an 
arbitrary message from inside the DMZ (and only the DMZ). It will not provide address book services, 
transaction-type functions (e.g. ACIDity), encryption, or non-repudiation. It will use Sun's JavaMail 1 .2, 
which is compatible with JDK 1.1.6, JDK 1.1.8 and JAF 1 .0. 1 . For the first release, XOLT Email will 
report a send failure to a designated email address. 

There are two pieces in XOLT Email: 1) a jar implementing I| and handling connection to one or more 
SNE servers via sockets. The JUT (also used in AV) and CM will be employed to manage the socket 
connection. 2) A program on the SNE servers to send email and react to failed deliveries. 

The XOLT email classes will offer the standard Ii interface on the UIS App servers and connect via sockets 
to the XOLT email program on the SNE server to provide mail origination services from inside the DMZ to 
destinations on the Internet. 

The program in the SNE servers will serve two purposes: a) send email to external destinations at the 
request of servlets in the DMZ; b) receive and react to notifications of failed deliveries. A log of all 
activity will be kept for diagnostic, customer service, and administrative purposes. It will check the origin 
of the socket connection to ensure that it is inside the DMZ. 

To handle 'bounced' email (i.e. failed deliveries), the XOLT email application will receive email and 
examine the headers and contents to determine the appropriate action. Bounced email will be logged and 
forwarded to the Merchant. The application will take care to avoid "loops" when handling "bounce 
notification" delivery failures by logging the failure and not sending further emails. Subsequent releases 
may deploy more sophisticated recovery techniques. The application will also be alert for denial of service 
attacks and spoofed inbound email. 

At the sender's request, transmission of the message may be delayed a number of minutes (max 30) to 
handle a race condition with PLD upload. This will be accomplished by temporarily storing the email on 
disk. 

Please notice that the diagram below specifies SMTP rather than sendmail. Sendmail merely connects via 
SMTP to the appropriate UPS mail server. Since JavaMail does the same, sendmail is viewed as 
unnecessary overhead. It is recognized by the writer that this may be an opinion uninformed opinion and 
may be subject to further discussion. A POP3 or IMAPI connection to the UPS mail server would similarly 
be more efficient than polling a disk file and somewhat more robust under significant load or attack. 
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UIS App Server 



SNE Servers 



ROW Servlets 




OLT Email 
Application 




Figure 10: XOLT Email Infrastructure 



App Servers to SNE Servers Communication 

The OLT Email component will communicate with the OLT application using TCP/IP Sockets. We would 
like to reserve a range of sockets, 7750 - 7780. The firewall must be configured for access to the SNE 
server. 



The XOLT Email Application will create logs on the SNE servers that need to be included in the log sweep 
process. For outbound email, the email component will log subject, send date, to email address, from email 
address (merchants), undeliverable email address. For "bounced email" the above information plus the first 
message body of the bounced mail (which contains the information why the send failed). 

We estimate that each outbound email will add 700 bytes to the log file; each bounced email message will 
add 1,500; and each unknown inbound message, 1,200. Please see Figure . 



3.5 Email/OPLD Race Condition 

There are two applications involved in order for a consumer to receive a Return Label, the Return Shipment 
application and the Label Recovery application. The processes are as follows: 

Return Shipment 

1 . The consumer submits a request to the merchant for a return label. 

2. The merchant then submits the request to UPS for a label. 

3. Behind the scenes UPS submits the Package Level Detail to the file system. Within the file system the 
label can be stored on one of six servers. 

4. The Package Level Detail is also submitted to OPLD for processing, may or may not be processed in 
real time. 

5. UPS Returns a XML to the merchant 

6. UPS sends the email to the consumer with a link to recover the label. 



Logging 
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Consumer 



OPLD 



6. Send E-Mail - 
1. Return Request 



UPS 



Merchant 



-2. XMLRequest J 



-4. PLD 



3. File Image- 



's. XML Response 



File 
System 




Label Recovery 

1 . Consumer clicks on the URL in the e-mail 

2. UPS gets the image from the file systems 

3. UPS returns the image to the browser 

4. Consumer receives the image 
OR 

1 . Consumer clicks on the URL in the e-mail 

2 . UPS gets the image from OPLD 

3. UPS returns the image to the browser 

4. Consumer receives the image 
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Analysis 

There are two problems with the above scenario: 

1 . The file systems are used as a holding area for the files that are going to be processed to OPLD. The 
file systems are removed every twenty-four hours. The Label Recovery application first calls to the 
files system to look for the image. Because Return Shipment can place the image on any one of four 
servers, Label Recovery application has a one in four chance of hitting the correct server. 

2. The Return Shipment application sends the Package Level Detail to OPLD for uploading and sends 
and e-mail to the consumer with a URL link. The processing time for OPLD varies from time-to-time. 
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The consumer may click on the URL as soon as they receive the e-mail and can view the label image. 
Other times, however, the period of time the user receives the e-mail and the period of time the user 
may be able to view the label may vary from 45 seconds to 7 minutes, and possibly 20 minutes during 
peak season. 



Solution 

At the sender's request, transmission of the e-mail message may be delayed a number of minutes (a 
maximum of 5 minutes during off time and 20 minutes during peak time) to handle a race condition with 
PLD upload. This will be accomplished by temporarily storing the email on disk. 
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4 Error Reporting and Monitoring 

In general, the new servlets will make use of the existing infrastructure. 

4.1 Monitoring 

XML OnLine Tools status monitoring will be augmented to monitor ROW, Label Recovery, and the XML 
OnLine Tools Email program. XML OnLine Tools monitoring is an extension of the UIS monitoring 
architecture and updates the same Oracle database used by UIS. This database is, in turn, monitored by 
production control via a web browser. Additionally, emails are sent to a distribution list when a problem is 
detected. To see monitoring page on one of our development servers try 
http://xmldev2.ismd.ups.com/servlet/OLTMonitor 



4.2 Logging 



The ROW servlets will use the UIS logging classes to log to the servlet logs in the same fashion as the 
other XML OnLine Tools. Activity and errors will be logged to a flat file. The XOLT Email component 
will also log to a log file in the SNE server(s). 

Each outbound email is estimated to add 700 bytes to the log; each bounced email, 1,500; and each 
unknown inbound email 1,200. Please see chart on page Error! Bookmark not defined.. 
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5 Resource Estimates 

There are two resource demand points: The ROW requests themselves and the Emails that flow from them. 
Both of these charts are based on marketing data which assume 33% of requests will be for 1A/3A and 66% 
will be for PRL. 



5.1 ROW Estimate 



Daily ROW Requests 




Figure 11: Daily ROW Requests 
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5.1 .1 ROW Bandwidth Requirements 

This is based on the above assumptions. 



Daily ROW Bandwidth (XML + Email) 
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Figure 12: Daily ROW Bandwidth 
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5.2 Email Volume Estimate 

Email volume is based on the following assumptions: 
For PRL 

95% of requests will be transmit the label via email 

75% of requests will also request a single Return Notification Email 

25% of requests will also request 2 Return Notification Emails 

For 1A/3A 

65% of requests will include a Pickup Notification emailed to the Consumer 
75% of requests will also want a single Return Notification Email 
25% of requests will also want 2 Return Notification Emails. 



Daily ROW Email Volume 
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2001 



Figure 13: Daily ROW Email Volume Projection 
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5.2.1 Email size 

Based on the above assumptions, the average email size will be 2K. 

Daily Email Size 
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Figure 14: Daily Email Size 
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Daily Email Log Size 

60n 




2001 

Figure 15: Daily Email Log Size 



02/13/0! - Version 1.0.6 



Page 29 of 35 



ppsj 



Returns on the Web IMT 300 Architecture 



5.3 ROW Load Distribution 

The ROW Load will vary over the course of a day or a week. These projections are based on the 
experience of the pilot with a single user, Buy.com. The utility of a single data point is limited and only 
slightly better than nothing at all. 



Projected Weelky Volume Distribution 




Mori Tues Wed Thurs Fri Sat Sun 



Figure 16: Projected Weekly Volume Distribution 
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Predicted Daily Volume Distribution 

9% -i 




02/13/01 - Version 1.0.6 



Page 31 of 35 



(ups) 



Returns on the Web IMT 300 Architecture 



Projected Daily Bandwidth (XML + Email) 



120.0 




Figure 18: Daily Bandwidth Projection 
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6 Dependencies 

6.1 UPS Systems 

ROW relies on a number of UPS components that currently lack key functionality and must be upgraded in 
time for this project to make it's schedule. 

UIS - UPS Internet Services components will provide the base functionality for generating a label 
FOSS - Support for return labels 

Billing - Support for additional services specified in the requirements by mid March 2001 
Email - UPS SMTP/POP email servers 

Drop Off Locator - Email text will include a URL to the Drop Off Locator with the origin zip code 
IMS - Licensing and Access will make use of IMS to determine eligibility of the request. 

6.2 Others 

Several other libraries and tools that are unique to this project will be employed: 

JavaMail - The email components will use version 1.2 of the Sun reference implementation of JavaMail 
with its SMTP class to communicate with the UPS mail servers. 

JavaBeans Activation Framework (JAF) - The JavaBeans Activation Framework (JAF) was developed 
and tested against Sun's JDK 1 . 1 .6 on the Solaris SPARC platform, and Windows 32 (both Windows 95, 
and Windows NT 4.0). This version of the JAF is written in Java (with no native code). It will run on any 
JDK(tm) 1.1 compatible virtual machine. 



6.3 Licensing 

Standard infrastructure software is used with the following exceptions: 
JavaMail 

The following is from the JavaMail FAQ f hrrp://www.iavasoftxoni/products/iavamail/FAO.htnil): 

Q: Is the JavaMail API implementation completely free? Can I ship it along with my product? 
A: Yes. The current release of the JavaMail API implementation, is completely free and you can include it 
in your product. This release includes IMAP, POP3, and SMTP providers as well. Please do read the 
LICENSE and ensure that you understand it. The JavaBeans Activation Framework is also free for use 
under a similar license. 



JavaBeans Activation Framework ( http://iava.sun.corn/products/iavabeans/glasgow/iaf.html ) 
No licensing information is available at this time 
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7 Appendices 

7. 1 Configura tion 



JDK version 1.1.6 (R4) and 1.1.8 
XML4J version 2.0.15 
Solaris 2.6 and 2.8 
JavaMail 1.2 

JavaBeans Activation Framework (JAF) 1.0.1 

Sendmail version 8.9.1 

Microsoft Exchange Server version 5.5 



7.2 Supporting Documents 

Return Services Marketing Plan, Executive Summary 12/21/2000 ("For Discussion Purposes") 

CIM Business Requirements: Returns on the Web 9/22/2000 

Evaluation for Returns on the Web XML Online Tools Version 1.12 10/19/2000 

XML OnLine Tools Returns on the Web Functional Requirements by Category Version 1 .5 175/2000 

Guiding Principles of UPS XML Document Design Version 1 . 1 .640/16/2000 

XML OnLine Tools I } Interface Specification Version 1.0.2 12/15/2000 



7.3 Open Issues 

1 . JavaMail v. UPS Servlet runners. The following text is found in the JavaMail notes 
(http://wwwjavasoft.com/products/javamail/NOTES.txt): 

We've received reports of problems using the JavaMail API in sen/lets driven by Netscape 
web servers. The error is that the Netscape servlet implementation doesn't support the 
java.awt.datatransfer.Transferable class which is used by the JAF. We recommend that you 
submit a bug report with Netscape. 

2. Logging in the SNE Server. The contents and size demands of the logs in the SNE server have yet to 
be defined. 



02/13/01 - Version 1.0.6 



Page 34 of 35 



!=I1=! Returns on the Web IMT 300 Architecture 



Index 

1A/3A 5, 12, 25, 27 

bounced 19 

browser 5,7, 17, 18, 24 

Consumer 5, 6, 7, 10, 11, 12, 27 

DES 18 

Documentation 9 

Drop Off Locator 33 

ec.ups.com 9 

email 6 

Email 5, 9, 1 1, 12, 15, 19, 24, 25, 27, 28, 33 

encryption 5,7, 11, 17, 18 

FOSS , 6,33 

Harbinger/Tandata 6 

How-to 6, 9 

HTML 17, 18 

HTTPS 18 

IMAPI 19 

IMS 15 > 17 > 33 

JAF 9, 19,33,34 I 

JavaBeans 33, 34 

JavaMail 9, 19, 33,34 

JDK 15, 19, 33, 34 

JRE , 9 

Label Delivery 17 

Label Recovery 4, 5, 7, 9, 13, 15, 17, 18, 24 

Licensing and Access 15, 33 

logging 9, 20, 24 

Merchant 5,6, 7, 10, 11, 12, 13, 17 

Microsoft Exchange Server 34 

Monitoring 4, 24 

Netscape 34 

Pickup Notification 10, 12, 27 

PLD 10, 17 

POP 33 

POP3 19,33 

PRL 5, 10, 11,25, 27 

prototype 5 

RA number 17 

Return Notification 10, 11, 12, 27 

ROW 9, 15, 17 

SDK 6, 9, 15, 18 

Shipping Tool 6, 7 

SMTP 19, 33 

SNE : 9, 19, 34 

Solaris '. 33, 34 

SSL 15, 18 

tracking 17 

UIS 5,6, 7,10,15, 17, 24, 33 

Vendor 5,6, 10, 11, 12 

XML4J 34 




02/13/01 - Version 1.0.6 



Page 35 of 35 




Electronic Commerce 



UPS Returns on the Web 

Deployment and Implementation Procedures 



mi 

'Hi 



Iljfll 



September 27, 2000 

Version 000927.01 



Hi 



III 



t 



in 



II 

► 

Hi- 



United Parcel Service, Inc. 

Enterprise Solutions 

Electronic Commerce Marketing Group 

Deployment Team 

55 Glenlake Pkwy 

Atlanta, GA 30328 

www.ups.com 
www.ec.ups.com 



EXHIBIT B 



' "-■ ^000 United Parcel Service, Inc. AH Rights Reserved. 
The use. disclosure, reproduction, modification transfer, or transmittal of this work for any purpose in any form or 
by any means without the written permission of United Parcel Service, Inc. is strictly prohibited. 

UPS Returns on the Web is a registered trademark of United Parcel Service, lik\ 
All other trade, a ; nd..*gy.iv«. marks are the property of their respective owners 



Electronic Commerce 



TABLE OF CONTENTScHAPTER i - introduction. 



1.1 


INTRODUCTION 


1 


1.2 


Scope 


2 


1.3 


Deployment Representative Responsibilities 


3 


1.4 


Project Timeline 


3 



CHAPTER 2 - ESTABLISHING BUSINESS RULES 4 



2.1 Customer Service Policy 



_4 
_4 
__7 
_9 
JO 
_11 
JJ. 
12 



2.2 Business Rules - Customer Service 



2.3 Business Rules - Finance and Account, 



2.4 Business Rules - Transportation a 



ng 



2.5 Additional Considerations 



2.6 Product Selection 



2.7 Shipping and Accessorial rvtty - 

2.8 Available Transportations < a?, 'i£tj|| rn i 

jiiiMiiiiiif 

CHAPTER 3 - PROGRAMMING 



.13 



3.1 Installation Overview 



13 



3.2 How It Works 


13 


33 Browser Version 


15 


3.4 General Programming Information . 


15 


Communication 


15 


XML 


15 


DTDS 


16 


Integration Requirements 


16 


Label Generation Request Method 


16 


Label Link Response Method 


18 


3.5 Shipment Reouest 


19 


Request DTD 


19 


Shipment Request Elements - Field Explanations 


22 


XML Shipment Request 


25 


Example of XML Document - Reouest ARS 


28 


Example of XML Document - Request Call Tag 


30 


Example of XML Document - Request ARS FOR NDA LETTER 


32 


©2000 United Parcel Service, Inc. Ail Rights Reserved. 
The use, disclosure, reproduction, modification transfer, or transmittal of this work for any purpose in any form or 
by any means without the written permission of United Parcel Service, Inc. is strictly prohibited. 



UPS Returns on the Web is a registered trademark of United Parcel Service, Inc. 
All other trade_and„sm.icc- mar,cs are tnc property of their respective owners. 



Dp 

3. 6 SnivM mTl&maQmtii& rce 

Response DTD 35 

Shipment Response Elements - Field Explanations 37 

XML SHIPMENT RESPONSE 39 

Example with explanations of fields: 39 

3.6 Error Codes 42 

Error Code Listing 42 



CHAPTER 4 - UPS RETURNS ON THE WEB IMPLEMENTATION 44 

4.1 Systems Testing Schedule 44 

4.2 Information Systems Auditing 44 

4.3 Product Release and Follow-up 44 

CHAPTER 5 - POST IMPLEMENTATION ^tllllll. k 45 

% 

5.1 Merchant Questionnaire ,<rti lt . llllllP 1 §|* 45 



CHAPTER 1 INTRODUCTION 11M t™ *™™, ™*™ ^ 1 

1 t I jk!i*n f\t\w i 5 J± It -f 

X71 XI" I l\\/I71Jv 1 t\Ji~~ - — 1* F "~ — ,r_r " - .- — .... — ■ 1 - ^ 



1.2 Scope 

13 Deployment Representative Responsibilities 


2 

2 


1*4 Project Timeline : 


3 


CHAPTER 2 ESTABLISHING BUSINESS RULES wm& m W mmm S mmm TO m S mnm»B 8 mn^ 




2A OjstomTjR Service Policy (CSP) : 


4 


2 J Business Rules Customer Service 


4 


23 Business Rules Finance anp Accounting 


8 


2 A Business Rules Transportation and Warehousing 


10 


2*5 Cross Functional Involvement 


« 


2,6 Product Selection 


14 


2 J Shipping and Accessorial Charges 


14 


2.8 Available Transportation Service Levels 


H 


CHAPTER 3 PROGRAMMING / INSTALLATION „„ 


**.u 17 


3 A Installation Overview 


VI 


3.2 How It Works 


17 


33 Browser Version 


21 


3.4 General Programming Information 


U 


HOW IS ALL TINS ACCOMPLISHED? 


2+ 


Communication 


24- 


XMh 


22 



©2000 United Parcel Service, Inc. Ail Rights Reserved. 
The use. disclosure, reproduction, modification transfer, or transmittal of this work for any purpose in any form or 
by any means without the written permission of United Parcel Service, Inc. is strictly prohibited. 



UPS Returns on the Web is a registered trademark of United Parcel Service, Inc. 
All other trade jmdj&r>icc. marks are the property of their respective owners 



lupsi 



m~rv. 



Electronic Commerce 



NTEGRiVH QN R EQU I rem ents 



L a bel G e neration Request Method 



L a b e l L i n k Response Method 



3.5 Sh ip m e nt R e que st 



Re q u est DTD 



Shipment Request Elements Field Explanations 



XML Shipment Request 



Example of XML Document — Request ARS 



Example or XML Document Request Call Tag 
3 .6 S hi pm ent Response 



Response DTD 



St upment Response Elements Field Explanations 



XML SHIPMENT RESPONSE 



Example with explanations of fields: 



-3$ 



-26 
-26 



-29 



-4? 



-43 
-42 



-44 
-46 




©2000 United Parcel Service. Inc. All Rights Reserved 
The use, disclosure, reproduction, modification transfer, or transmittal of this work for any purpose in any form or 
by any means without the written permission of United Parcel Service, Inc. is strictly prohibited. 



UPS Returns on the Web is a registered trademark of United Parcel Service. Inc. 
All other trade jndjervififi. marks are the property of their respective owners. 



UPS Returns on the Web 

Deployment and Implementation Guide 




Electronic Commerce 



Chapter 1 - Introduction 



1.1 Introduction 



These UPS Returns on the Web Deployment and Implementation Procedures (the "Procedures") 
are intended to serve as guidance with respect to your deployment and implementation of the 
UPS Returns on the Web service described herein and are not intended to, and do not, create any 
representations or warranties with respect to the UPS Returns on the Web service. UPS may 
revise and update these Procedures at any time. Please consult with UPS to ensure that you are 
using the most current version of the Procedures. 

UPS Returns on the Web service has been developed to,^Jp facilitate the reverse logistics 
process for on-line merchants. Return rates for mercharffili^jpurchased on the web run higher 
than return rates of traditional retail channels. Whikjjfche pre$||ping wisdom dictates that those 
merchants with physical locations have an edge oveithi&b merchants, in fact, over 94% of returns 
are shipped back to the merchant. Most considers wB^jJiave made purchases on the web 



indicate that they would prefer to return mere] 
Lastly, 89% of on-line shoppers indicatejijthat a 
buying decisions. (Source: www.bizraf8||& |jj08/(a)) 

fill I ^ * ' 
Many distribution centers do not wm 

centers have no way of predicting t$!| 

way of linking customer returns with 



the same way they purchased it - on-line! 
ant's return policy influences their on-line 



enective means for processing returns. Distribution 
ival of return merchandise. Merchants have no effective 
e customer's account information, and merchants are 
often unable to identify unauthorized returns in their warehouse. Useful inventory often sits idly 
in corners of the warehouse. 



UPS Returns on the Web offers a solution for many of these issues. Using UPS ARS 
(Authorized Return Service) and On-line Call Tag Service, merchants are better able to control 
and identify returns. UPS Returns on the Web reduces the amount of customer service 
resources required to deal with returns? by offering the merchant's customer a self-service, web- 
enabled returns mechanism. 

UPS Returns on the Web enables merchants to track their inbound returns and to link returns to 
the UPS 1Z tracking number. UPS Returns on the Web provides the critical information links 
the merchant requires to reconcile customer accounts and to quickly identify potential problems 
with products. 

UPS Returns on the Web allows the merchant's end customer to print a UPS ARS return label 
from their own computer 24 hours a day, 7 days a week. The merchant will enjoy a streamlined, 
more cost effective, efficient, and better managed process. 

The accompanying document will provide a merchant's technical support staff with the 
information needed to use the UPS Returns on the Web service. 
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UPS Returns on the Web has been created to provide merchants with an alternative to the 
traditional method of managing the reverse logistics process. This service is not a general 
service offering at this time. It is provided to merchants as a contract service, which promotes a 
convenient, cost saving, and controlled approach for retrieving merchandise from customers. 

The service begins UPS and th e UPS account holding customer (merchant) execute t The UPS 
Returns on the Web Contract Carrier Pilot Agreement (the "Agreement") , to be entered into by 
and between UPS and the UPS account-holding customer (the "merchant"), . The agreement sets 
forth the terms and conditions governing the service, including service start date and the rates 
and fees applicable thereto, contains the amount UPS will charge for e ach shipment. These 
charg e s include a transportation charge and transaction fe e . 

The service enables M merchants to provide participatins ||ynsumers (the " ecustomers") with the 
"ARS Label" and "Electronic Call Tag Pickup" online r! itu%shipping one or mor e options^ef 



supplying th e return ord e r information . The "ARS< 



option enables merchants to 



send UPS return labels to customers via email for pfaljlftient of return packages into the UPS 



shipping system. Merchants electronically sub| to a custftener's package return information 



which generates a UPS label that is sent to the nj| ffij|*nt in the form of a digitized image. Th e 



merchant is then responsible for forw; 



t the 



label to the customer for placement of the 



customer's package into the UPS shippf 



m. The "Electronic Call Tag Pickup" option will 



lest^P^fe. which generates a Call Tag that will initiate the 
1 k customer's return package from the location to which the 



transmit a return package pickup 



dispatch of a UPS driver to pick 



x , _ . ... 7 _. ._ ^____^_^„^ igi -J feu ^ 

package was originally shipped to si^BWomer. -Two examples of the options for customer 
contact are through existing or future customer service phone centers and/or the merchant's 
website. It may be n e ce s sary for a customer or the merchant to initiate th e proce s s for r e turning 
a shipment. The merchant gathers customer and product information, and assigns the necessary 
return merchandise authorization number (RMA#). A UPS compliant shipping label is then 
issued to merchant for distribution to t he customer. The customer will package, label, and 
submits parcels to UPS. [CONFIRM] 

This s e nde e may bo used along with other UPS r e turn servic e s that ar e in place, including 
Authorized R e turn Sendee (ARS) and Call Tag servic e . UPS Returns on the Web does not 
support Hundredweight servicer Service is limited to domestic origins and destinations within 
the 48 contiguous U nited States. 



1.2 Scope 

The implementation is completed by the merchant with the assistance of the UPS Returns on the 
Web deployment team. UPS will assign a deployment representative who will work with a 
project manager designated by the merchant throughout the implementation. The merchant's 
responsibility will be to identify the key elements and performance requirements of the return 
service. The merchant will supply resources related to IT integration and programming during 
installation and implementation. [DO WE SUPPLY A DEPLOYMENT TEAM IN EACH 
INSTANCE AND ARE THESE DEPLOYMENT SERVICES FREE OF CHARGE?! 
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The following questions set forth in Chapter 2 wil lare designed to help the merchant craft the 
business rules procedures for a web return product that will meet their Customer Service Policy 
£CSP^) and result in a positive return experience for the merchant and theits customers. These 
questions, however, are not designed to be all-inclusive. Rather, they are presented to assist 
merchants with return issues and to address the needs of the merchant and the customer. 



1.3 Deployment Representative Responsibilities 



A UPS representative will be assigned by UPS available to p rovide advice during the 
deployment and implementation of the UPS Returns on the Web service. The UPS deployment 
representative will act as an interm e diary b e tween the merchant and UPS and will facilitate a ssist 
the merchant during the implementation process and in developing appropriate return procedures 
consistent with the service answering the business rules jmaysis questions, and anticipate th e 



needs of th e m e rchant during the implementation pr> 
project . 



1.4 Pro 




UPS Returns on the Web 



The projected time to complete the enti^L |*S rJi iirns on the Web installation is estimated to 
be approximately 30 days, unless o^erwisqimBlcated in the Agreement. Individual cu s tom e r 
merchant circumstances can affe^P^ftengtn^bf time needed to complete the deployment and 
implementation process. The followfja^estimate is establish e d set forth as a guideline only . 
AMerchants should establish a project Timeline prior to deployment that is establish e d by the 
merchant should identifiesy the-key target dates for implementatio n, and b e used by th e merchant 
prior to d e ploym e nt to insure the proper scheduling of resources. 

Evaluate Custom e r Service Policy ( CSP) and establish business rules 
Establish the performance criteria and the testing schedule 
Complete implementation 
Post-implementation follow-up 



Days 


1 


- 3 


Days 


4 


-7 


Days 


8 


-30 


Days 


15 


-30 
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Chapter 2 - Establishing Business Rules 

It is recommended that the merchant involve affected departments, functions and vendors in the 
design of the return process. The new process of UPS Returns on the Web may affect 
established custom e r service policies ( CSPs) and vendor relationships. Operational costs and 
internal processes such as receiving, restocking, and inventory management may be affected. 
Financial considerations that involv e concerning the value of products, the crediting of accounts, 
or the_sending of refunds to customers should may necessitate the involve ment of other functions 
or departments. In addition, the merchant's CRM strategy eanmav be enhanced. The marketing 
department may want to take advantage of the improved capability resulting from this 
implementation. 

2.1 Customer Servi^lSLlicy 

# \ 

The merchant's customer service policy should be u|ypas a guide for deployment and 
implementation of UPS Returns on the Web^ervice. l^ior to deployment, the UPS deployment 
representative and the merchant principals shoffil|j|cuss established return policies and 
procedures to determine if changes, imnn^emenfir an^or additions need to be made to the CSP 
as a result of this product implementati^ ^ RE: CONSULTING FEES1 

2.2 1^1 Jily&s Rules - Customer Service 

For the reverse logistics channel, the merchant should frequently refer to the CSP in order to 
determine functional and technical requirements. The CSP will also serve as the impetus for 
operational changes and process improvements. The merchant's return service should offer a 
variety of service combinations to improve customer service. 

The following questions will s e rv e a re designed to assist the merchant in meeting customer 
service expectations? and to will help a ddress some of the concerns associated with reverse 
logistics: 

■ How will UPS Returns on the Web affect your current return policy? 

■ How many days from ship (or receipt) date can a customer return a product? 

> When does the return clock start? 

> How will this information be communicated to the customer? 

■ Do you have any product(s) that can be returned unconditionally? 

> You would need to outline your product identification requirements by: 
Name, type, SKU number, manufacturer, and established database 
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> How will this information be made available to the web site and customer service 
personnel? 

■ What levels of transportation service should be made available for returns? 

> Ground, expedited, express, Call Tag, ARS 

> Products - letters and packages 

> When should different services be used? 

> How does weight, dimensions, and other package characteristics affect transportation 
service decisions? 

■ Do you want to identify specific products to be retui^|lm,directly to vendors, suppliers and 



■ Under what situations would you charge for shipping a return? 

■ What criteria would be used to calculate these charges? 

■ Are replacements for exchanges, wrong items, color, etc. shipped automatically? 

■ Do you have a need to identify high repeat return customers? 

> Data mining 

> Trend reports 

> Cost controls 

■ How do customer service personnel currently answer . . . 

> Regular shipment inquiries? 

> Return shipment inquiries? 

■ Do you have a need for a customer to track a package from your web site? 




> Dees -Are customers entitfmTOireturll 1 g uaranteed or warranted merchandise 
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> Invites the customer back to the website. 

> Provides an opportunity for a customer to come back to you. 

> UPS OnLine Tools available. 

How will you help your customers who are unable to print a label? 

> How would they be able to tell you that they cannot print? 

> Would you be able to print and mail? 

> Offer alternate email address options (such as customer's work email)? 

How will you assist your customers who have questions about credit or refund inquiry? 

> Reference numbers used. ^ M|h 

> Q&Apage, *M|{ |f ||». 

> Email option, 



|Hi> 



Hi 



> bmail option, im^ 

> Customer Service phone number,... % 

Will you have a need for proof that yllf||^tomer gave the return shipment to UPS? 

> Call tag vs. ARS, •<i|l!!\ 

Ulifllr 

> Pickup or drop-off locations, "Jl 1 

> Tracking number usage, 

> Reference number usage. 

How will you handle packing needs of your customer for safe transport? 

> Container requirements, 

> Packing requirements, 

> Labeling requirements, 

> Paper, 

How do you currently issue refunds or credit? 

> Credit account or credit card, 

> Mail check, 

> Merchandise coupon. 

Are you accepting any products for repair? 

> Repair in house. 
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> Repair off site. 

■ Can a delay in time-in-transit affect customer or merchant satisfaction? 

> Shelf life, 

> Product quality. 



2.3 Business Rules - Finance and Accounting 

The finance department of the merchant may be affected by the UPS Returns on the Web 
service. The following questions wi Uare designed to assist the accounting and finance 
department in identifying needs and the e valuation of th e fl tjaluating current p roc es s involving 
return shipments procedures . ^^Mh» 

Ih % 



(ups| 
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Which products are customers entitled to return 



customers entitled to return or are authorizl jp^redit only? 
What is your refund polic y for a re^ ^ 



i, 




warrant refunds ? Which products are 



> Only when return is auth^ 

> Whenever shipment is returaMp 

> Refund only in certain circumstances? 

■ In the original order, do you pass on the shipping charges to customers? 

■ Do your refunds include the paid-shipping charges paid for by the customer? 

■ Do your refunds include any special charges paid for by the customer? 

> If you do refund them, how do you handle charges? 

> Do you include any taxes paid by the customer? 

> Are handling charges refunded? 

> Are there miscellaneous charges (added into processing)? 

■ Do you pass on charges to ship a replacement item if the customer wants a different size, 
color, etc.? 

> Shipping only.. 

> Handling only. 
SShipping and handling. 

e 

©2000 United Parcel Service, Inc. All Rights Reserved. 
The use, disclosure, reproduction, modification transfer, or transmittal of this work for any purpose in any form or 
by any means without the written permission of United Parcel Service. Inc. is strictly prohibited. 



UPS Returns on the Web 

Deployment and Implementation Guide 



3E 



Do you pass on shipping charges to reship if an order was filled inaccurately? 

> How would you identify this mistake? 

> How would your customer tell you it was a mistake? 

How could a customer request a refund or credit? 

> Check mailed. 

> Credit account or credit card. 

> Merchandise coupon credit on future purchases^ 



(upsj 

^* — -"e 
Electronic Commerce 



Do you charge your customer a restocking fee for returned items? 

> What options would a customer have to pay t le lftJI}||j 

> Will you be able to handle credit card trans^ij iofas for Jfiipping charges, credits or 



refunds? 

Do you have any products of extremdi^|ow^u^? 
> Would you want them included Mm ptlfy&s? 



1% 



> Do you have any product'liPby clable value? 

Dartrn 



How would the accounting department handle returned items coming back into inventory? 
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2.4 Business Rules - Transportation and Warehousing 

The transportation and warehousing business rules should align with the CSP. Some of the 
elements of concern for customer satisfaction are related to time-in-transit standards, how to 
apply the credit, repair or replacement possibilities, replacement shipment time-in-transit 
requirements, damaged products, inventory control, inbound process, and restocking procedures. 

Thes e following questions are designed to assist the merchant in would be r e levant to managing 
warehouse activity: 

■ What departments do you notify when a return has 3rr ^^ mto * e warehouse? 

> Accounting, Collections, AR, AP, ^ hty 

> Customer Service. ^ 

> Sales and Marketing. 

■ -What information will these departm| 



What paperwork do you use to-sOroces! 



> Handwritten document. 

> Inbound Manifest/invoices/padlSng slips. 

> Advanced shipment notifications. 

■ What time of the day are returns processed? 

> Are there time conflicts? 

> Are there space restrictions? 

> Are their peak times during the day, week, and month? 

■ How many days of return inventory are left unprocessed daily? 

■ How do you measure your warehouse processing performance? 

■ How many carriers are involved in the transportation of returns to the warehouse? 

> TL/LTL carriers, 

> Other small package carriers. 

■ How does restocking affect the current inventory levels? 

> How should returns be accounted for in inventory? 

> Does product need to be placed back in inventory before it is shipped again? 
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2.5 Additional Considerations 

Are you planning to include any of your vendors in the service? 

> Will a vendor be receiving return products from your customers? 

> Will a vendor advertise the service? 

> Will a vendor be shipping return products to you? 

If so, how will you include the vendor in the entire information process? 

Will training be needed to educate your workforce about this service? 

> Sales personnel. 

> Customer Service personnel,. c jj|J^ ^ % 

> Accounting. it ^ijjj 




WSJ 



e 
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> Marketing, 'Hjjj||),„. 

> Warehousing personnel. <l|fP% 

■ How will you inform employ^|Htoout tftfe service? 

> Formalized training? ^(Jl 1 

> Through informal communications,. 

> Meetings,. 

■ Will you update customer service call centers with new information as the service expands? 

> How will this be accomplished? 

> What will b e th e frequ e nc vH ow often ? 
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2.6 Product Selection 



The merchant will need to identify the valid reasons for returning product as well as which 
specific SKUs will be accepted for return. 

Several options will be available for merchandise return, and the merchant will choose the UPS 
services that best meet their business requirements. Consideration will need to be given to issues 
such as: 

> The customer did not want or refused a shipment. 
Merchandise was damaged,. 



r ivierciianuise was uamagcu.. 

> Wrong items were shipped. <rij||L 
Attention will need to be given to issues suiroynding^m-standard products such as liquids. 



> Whether the customer wants a replacement, aicre&t^ha refund. 



breakables, perishables, and irregularly shapeajbfyweigfJ&d products. Special considerations 

ffici 



should be made for the return of partial oraen 
partial return and the packing material 4jjjjj jju 



ers. Hbfpp^ntly, the carton size is too large for the 
fficmht to protect contents. 

In addition, return for repair proQjlllUltes- anal Value limitations should be established. Very low 
value items should be cost-justifiealbefik-e being eligible for return service. In most cases it may 
be less costly to scrap low value items(lcnd issue credit to these customers. The merchant's web 
site should reflect customer choices that coincide with the merchant's decisions regarding these 
issues. 



2.7 Shipping and Accessorial Charges 

Are there SKUs for which oversized charges need to be applied? Does the merchant have the 
dimension sizes? These dimension sizes will need to be sent in the XML file to correctly apply 
oversize charges. Does the merchant have SKUs for which additional handling charges need to 
be applied? The merchant needs to plan how returns charges will be applied. The merchant may 
need to absorb the charges in instances where merchandise was shipped in error. The merchant 
may want to absorb the charges if the customer is a "good customer". Obviously, "good 
| customer" needs to be carefully defined by establishing limiting criteria. 

In instances where the customer will charged, the merchant needs to decide how much to charge, 
and how to apply the charges (e.g., ©bill to the existing credit card number in the merchant's 
database, or ask for credit card information at the point-of-contact). In any event, the merchant 
must understand that UPS charges the merchant a shipping charge and accessorial fee for each 
use of the service. UPS will not collect any charges directly from the merchant's customer. 



1) 
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2,8 Available Transportation Service Levels 
The following UPS Services are applicable for return service. 



> UPS Next Day Air package 1 to 150 pounds, UPS Next Day Air Letter 

> UPS 2 nd Day Air package 1 to 1 50 pounds, UPS 2 nd Day Air Letter 

> UPS 3 Day Select package 1 to 150 pounds 

> UPS Ground packages 1 to 150 pounds 

> UPS ARS service < 

> UPS Call Tag Service <<P 



nee will be available'toidhd from 



UPS Returns on the Web service 
contiguous United States. t tu 
Ground or 3 Day Select Service packages dropfjet 

Pickup service through our UPS Call T$|j| j^ c< 

UPS Air services are available titif|ffiffit| pur fell Tags 

w 

UPS Hundredweight service is not available for UPS Returns on the Web. 



addresses within the 48 



^f Saturday or Sunday will ship on Monday. 
5 available Monday through Friday. 



service. 
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Chapter 3 - Programming / Installation 

3.1 Installation Overview 

| This chapter covers the UPS Returns on the Web technical specifications. -Information in this 
chapter includes the Request and Response XML document requirements as well as a description 
of data elements and error codes. Sample code is provided as a guideline. Merchants will need 
to create proprietary code to meet their individual functional and technical requirements. 



3.2 How It Works 

This section provides an example of how a customer co^flJtfcfluest a return via a web site. 

lll J " item(s). The customer should have the 



A customer accesses the merchant's website to re 





|jji»|^lMLur.::; _ m I H 






>■ '4a ■ ; 1 ■ — ^ - i ~ — ~~ ' ' 

Wmm 1 Co! ' t,l!;,e - ; ' Cm,Cfi • - •'• 



ability to reference their order history and select an order that they have already placed. 
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The customer is able to process a returfilMHed on the business rules the merchant has established. 
The customer could be directed to jygrify tHbir U&dress and information about the order. The 
merchant can direct a customer t$ad«ftpeni channel (Call Center) if the verification process is 
not satisfied. If the customer meet^Wjpecessary criteria the following options would be made 
available: 1 



1 . The customer return product via UPS AR S (Authorized Return Service). 



With ARS, the following pptions are available: 

> The customer can print the UPS ARS label directly from their PC. This is accomplished 
by displaying the label image on the customer's web browser or by sending the customer 
an email message that contains a URL link to the ARS label image. 

> The merchant can receive the URL containing the label image giving the merchant the 
capability to print and mail a label to the customer. This option would be beneficial if the 
customer did not have access to a printer. 

> It is possible to send emails containing the URL label image to both the customer and the 
merchant. This enables the customer and merchant to save the URL and print it at a later 
time or at a different location. 



2. The customer can request a UPS Call Tag pickup. This gives the customer the option teof 
have- ahaving a UPS Driver pick up the return from their location and send it to the merchant 
via UPS Next Day Air, 2 nd Day Air, 3 Day Select or Ground Service. 
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3.3 Browser Version 

It should be noted that UPS generates the ARS label image in a PNG format. The *.PNG image 
file can only be viewed and printed in the Microsoft® Internet Explorer web browser and 
or Netscape Navigator web browser Versions 4.0 and higher. The MAC Mac version of 
Netscape 's web browser is not compatible with the PNG format. The merchant's web 
application should test for the customer's browser compatibility. There is Java script available 
| which allows a web server to check a customer's web browser version as the customer logs on to 
the merchant's site. Utilizing this feature would allow the merchant's site to re-direct customers 
| with non-compliant browsers. -The merchant will need to design an alternative to processing 
returns for these exceptions. 



3.4 General Programmingjf^prmation 
Communication *m it#f|j 



An e-commerce application invokes UPS Returns on % Web by initiating Hypertext Transfer 



Protocol (HTTP) communication with the serv% Hbsting UPS Returns on the Web. HTTP is an 



f 

^Hbstin] 

application-level protocol for distribute^teollabomtive^ and hypermedia information systems 
HTTP is a generic protocol used to coi^pjcate Between user agents and proxies/gateways to 
other Internet systems, including thgse su$Mfe by SMTP, NNTP, FTP, Gopher, and WAIS. 
HTTP allows a user to readily e^Bharl|b XML-formatted messages. 

w 

XML 1 

extensible Markup Language (XML) is an open standard for defining markup languages to 
represent structured information over the web. XML documents are used for business-to- 
business communication and data interchange between dissimilar systems. Network transfer 
occurs with standard HTTP over TCP/IP. 

UPS Returns on the Web uses XML documents to communicate with e-commerce applications. 
XML, like its cousin HTML, is a subset of Standard Generalized Markup Language (SGML). 
Whereas HTML is used to tag words, pictures, and other media so that they can be rendered the 
same way by different browsers, XML is used to tag documents and data so that different 
software consumers can interpret them without ambiguity. 

For example, consider the following text: 

1Z0597X90219590035 

This string can be interpreted in many ways — an invoice number, a purchase order number, a 
random sequence of characters (noise). Using XML to tag the string removes the ambiguity: 

<TRACKINGNUMBER>1Z0597X90219590035</TRACKINGNUMBER> 
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The tagging mechanism of XML guarantees that if documents are structured properly, the data 
can always be parsed. 



UPS Returns on the Web supports XML 1.0 specification. 
(http://www.w3 .org/TR/ 1 998/REC-xml- 1 99802 1 0/). 



DTDs 

A Document Type Definition (DTD) is a set of rules that specifies how to use XML markup. It 
contains specifications for each element, including what the element's attributes are, what values 
the attributes can take on, and what elements can be contained in others. Trading partners use 
DTDs as interface contracts (for example, input/output specifications that programmers use to 
craft software). DTDs are also used by software to validatolhe syntax of XML documents. 

Integration Requirements <jj> 

To integrate UPS Returns on the Web into an e-coH||jiferce application, proprietary 
programming code must be developed that ad(| 
Returns on the Web process. Merchants can 



HTTP communication across the Inte: 
XML documents. 



tits: 




<ilPJlii % 

It is recommended that an XML p&seyijjvith an Application Programming Interface (API), be 
used to manipulate XML documentilfyjjjlere are several commercial XML parsers on the market. 
Freeware versions are also available. 



Label Generation Request Method 

To generate a request for a return label the merchant passes a valid XML Request document to 
the UPS web server. Included in the Request document is the merchant's Return URL. 

An XML Response document will be returned to the merchant The Response file will contain 
all relevant information regarding the return as well as a URL to the label image. The merchant 
can display this URL on the customer's browser for easy access. If indicated in the XML 
Request, UPS will also send an e-mail containing the label URL to the customer and the 
merchant. 



The following code snippet is from a sample file called sendxml.asp, demonstrating how a 
merchant could send a Request document to the UPS Returns on the Web site. 

Initialize the URL to the Returns on the Web site. This is the URL to post the XML Document. 

<% 

strPOSTURL = n ^9MMBMm^^MMimiim^ 
%> 

<HtmI> 

<FORM action= M <%=strPOSTURL%>" method=post> 



Put XML into textarea field so it can be posted as a variable. 

16 

©2000 United Parcel Service, Inc. All Rights Reserved. 
The use, disclosure, reproduction, modification transfer, or transmittal of this work for any purpose in any form or 
by any means without the written permission of United Parcel Service, Inc. is strictly prohibited. 



UPS Returns on the Web 

Deployment and Implementation Guide 




Electronic Commerce 



<textarea name=XML id=XML rows=35 cols=80> 
<?xml version="1.0"?> 

<!DOCTYPE SHIPMENTREQUEST SYSTEM " http://www.upsreturnservices.com/dtd/ sh ipreqtest.dtd "> 
<SHIPMENTREQUEST> 
<LOGIN> 

<L0GiNID>UPSTEST</L0GINID> 
<PASSWORD>UPSTEST</PASSWORD> 
</L0GIN> 
</SHIPMENTREQUEST> 
</textarea> 
<BR> 

<input type=submit value- 'SEND"> 



The XML response will be posted to the RETURNURIliyariable specified in the XML 
Request document. 



<input type=hidden value= M http://207.16.70.48/client/saveo: 



Merchant specific data will be posted back 
relationships that may occur. 

<input type=hidden name - 'MERCHANTO 




</form> 
</html> 



k to the R^jj^RNU 



name— "RETURNURL M > 
so merchant can control any data 

alue="P0123"> 
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Label Link Response Method 

Once the request document is processed, a response post is performed to the RETURNURL 
specified in the request document. The response post will contain the following information and 
can be processed similar to saveorder.asp: 



<% 

'traverse through all variables 
dim oPostElm 

For Each oPostElm In Request. Form 

Response. Write(oPostElm & " = " & Request. Form(oPostEIm) & "<br>") 

Next 
%> 
<br> 

<a href=<%=Request.Form("LABELURL")%> target="newindo$Pciick here to view label </a> 
</html> ™%u 

.mi", 

The execution of this program results in the followm^jjl^ 

LABELURL = http://63.74.215.82/Progistics/XML Pr^e^/Se^^ 
MERCHANTORDERNUMBER = P0123 m 
RESPONSESTATUSCODE = 0 4h% 
RESPONSESTATUSDESCRIPTION = SuccesSM fM\{u 
ERROR = ONo error H|h. 
ERRORDESCRIPTION = No error, Ndl|jToH,(hlo error, No Error, No error 
CONSIGNEEREFERENCE =111 %lM 
TRACKINGNUMBER = 1Z 12345627 1245 1056 
RETURNURL = http://207.16.70.48/client/saveorder.asp 
SHIPPERREFERENCE = 1NV1 1 1 
SHIPPER = TEX 



Click here to view label 

An error in execution of this program results in the following variables being posted back to the 
RETURNURL. Below are two examples: 

RESPONSESTATUSCODE = 609 

RESPONSESTATUSDESCRIPTION = Unable to process request 
ERRORDESCRIPTION = Invalid Login ID. Verify Login ID with System Administrator. 
RETURNURL = http://207.16.70.48/client/saveorder.asp 
MERCHANTORDERNUMBER = P0123 
OR 

RESPONSESTATUSCODE = 2 
RESPONSESTATUSDESCRIPTION = Failure 

ERRORDESCRIPTION = Package #1: Required attribute SHIPPER is missing 
MERCHANTSPECIFICURL = MERCHANTORDERNUMBER 
RETURNURL = http://207.16.70.48/client/saveorder.asp 
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3.5 Shipment Request 

Request DTD 

Generation of an ARS or Call Tag starts with a SHIPMENT REQUEST. An XML 
SHIPMENTREQUEST must be validated against the DTD SHIPMENTREQUEST.dtd: 

<?xml version="1.0" encoding="UTF-8"?> 

<!ELEMENT SHIPMENTREQUEST (LOGIN, DEF ATTRIBUTES, PACKAGES, SHIPMENTSERVICE, 
CLOSEOUTMODE, PACKAGEDETAIL)> 



<! ELEMENT LOGIN (LOGINID, PASSWORD^ 
<!ELEMENT LOGINID (#PCDATA)> 
<!ELEMENT PASSWORD (#PCDATA)> 



x. 



<! ELEMENT DEFATTR1B UTES (CONSIGNEE, SHlte 
SHIPMENTSERVICEOPTIONS?, SHIPNOTipj ! /TIONf 



<!ELEMENT CONSIGNEE (COMPANY, r 

POSTALCODE, PHONE?, COUNTR^|ffij^OL)Hl|j. 

<!ELEMENT COMPANY (#PCDATA)> 

<!ELEMENT CONTACT (#PCDATA)> 

<!ELEMENT ADDRESS 1 (#PCDATA)> 

<!ELEMENT ADDRESS2 (#PCDATA)> 

<!ELEMENT CITY (#PCDATA)> 

<!ELEMENT STATEPROVINCE (#PCDATA)> 

<!ELEMENT POSTALCODE (#PCDATA)> 

<!ELEMENT PHONE (#PCDATA)> 

<!ELEMENT COUNTRYSYMBOL (#PCDATA)> 

<!ELEMENT SHIPPERINFO (SHIPPER)> 

<!ELEMENT SHIPPER (#PCDATA)> 

<!ELEMENT TERMS (#PCDATA)> 

<! ELEMENT CURRENCYCODE (#PCDATA)> 

<! ELEMENT SHIPDATE (#PCDATA)> 



FO, TERMS, CURRENCYCODE? SHIPDA i E, 
ADDRESS 1, ADDRESS2?, CITY, STATEPROVINCE, 
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<!ELEMENT SHIPMENTSERVICEOPTIONS (DECLAREDVALUE?)> 

<! ELEMENT DECLAREDVALUE (CURRENCYCODE, MONETARY V A LUE)> 

<!ELEMENT MONET ARYVALUE (#PCDATA)> 

<!ELEMENT SHIPNOTIFICATION (EMAIL)> 

<!ELEMENT EMAIL (CONSIGNEEEMAIL?, SHIPPEREMAIL?, EMAILRETURNADDRESS, 
EMAILSUBJECT, EMAILMESSAGE)> 

<!ELEMENT CONSIGNEEEMAIL (#PCDATA)> 

<!ELEMENT SHIPPEREMAIL (#PCDATA)> 

<!ELEMENT EMAILRETURNADDRESS (#PCDATA)> <|||j||j. 
<!ELEMENT EMAILSUBJECT (#PCDATA)> <S}\u ^ 



<!ELEMENT EMAILMESSAGETEXT (#PCD/ 



!EI EMENT EMAIL ME JSAGE (EMAILMESSAG^yjEXT+)> "|j 
<!ELEMENT PACKAGES (PKG)> ftf^. 



<! ELEMENT PKG (PKG WEIGHT, DlBffiN&ON, PACKAGING, REFERENCE, 
PACKAGESERVICEOPTIONS, LAB EL j^r|||aT?)> 

<!ELEMENT PKGWEIGHT (WEIGHTUNITS, WEIGHTVALUE)> 

<!ELEMENT WEIGHTUNITS (#PCDATA)> 

<!ELEMENT WEIGHTVALUE (#PCDATA)> 

<!ELEMENT DIMENSION (DIMUNITS, DIMVALUE)> 

<!ELEMENT DIMUNITS (#PCDATA)> 

<!ELEMENT DIMVALUE (#PCDATA)> 

<!ELEMENT PACKAGING (#PCDATA)> 

<!ELEMENT REFERENCE (CONSIGNEEREFERENCE, SHIPPERREFERENCE)> 
<!ELEMENT CONSIGNEEREFERENCE (#PCDATA)> 
<! ELEMENT SHIPPERREFERENCE (#PCDATA)> 

<!ELEMENT PACKAGESERVICEOPTIONS (OVERSIZE?, ADDITIONALHANDLING?, CALLTAG?, 
RETURNDELIVERY)> 

<! ELEMENT OVERSIZE (#PCDATA)> 

<! ELEMENT ADDITIONALHANDLING (#PCDATA)> 

20 
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<!ELEMENT CALLTAG (CALLTAGFLAG, CALLTAGDESCRIPTION)> 
<!ELEMENT CALLTAGFLAG (#PCDATA)> 
<!ELEMENT CALLTAGDESCRIPTION (#PCDATA)> 

<!ELEMENT RETURNDELIVERY (RETURNDELIVERYFLAG, RETURNDELIVERYDESCRIPTION)> 
<!ELEMENT RETURNDELIVERYFLAG (#PCDATA)> 
<!ELEMENT RETURNDELIVERYDESCRIPTION (#PCDATA)> 
<!ELEMENT LABELFORMAT (#PCDATA)> 
<! ELEMENT SHIPMENTSERVICE (SCS)> 



<!ELEMENT CLOSEOUTMODE (#PCDATA)> ( JJk 
<! ELEMENT PACKAGEDETAIL (#PCDATA)> tt % Pl> 



<!ELEMENT SCS (#PCDATA)> 
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Shipment Request Elements - Field Explanations 

The following table describes each of the fields contained in a shipment request that will create 
either an ARS label or generate a Call Tag for package pickup. Please note which elements are 
required and which elements are optional. 



TAG 


REQUIRED? 
YorN 


CHARACTER 
LENGTH 
MAX 


DESCRIPTION 


SHIPREQUEST 


Y 




OPENING TAG 


LOGIN 


Y 




REQUIRED TAG 


LOGINID 


Y 




ID assigned by Ecommerce Enterprise group 


PASSWORD 


Y 




Password assigned by Ecommerce Enterprise group 


DEF ATTRIBUTES 


Y 




REQUIRED TAG 


CONSIGNEE 


Y 




OPENING TAG FOR CONSIGNEE ELEMENTS 


COMPANY 


Y 


30 <|l|!| 


COMPANY OR CONSIGNEE NAME OF ARS 
tUSER 


CONTACT 


N 




'PS USER CONTACT NAME 


ADDRESS 1 


Y 




STREET NAME AND NUMBER OF ARS USER 


ADDRESS2 


N 


III. 3 %. 
' fa * 1 


APT#, DEPT NAME OR OTHER DESCRIPTION 
OF ADDITIONAL ADDRESS INFORMATION 


CITY 




Jkllf 


CITY NAME OF ARS USER 


STATEPROVINCE 






2 CHARACTER STATE ABBREVIATION i.e.; 
NY,GA,IL 


POSTALCODE 






5 DIGIT ZIP or ZIP+4 CODE OF ARS USER 


PHONE 




15 


OPTIONAL FIELD 


COUNTRYSYMBOL 






MUST BE SET TO 
"United States" 


SHIPPERINFO 






REQUIRED TAG 


SHIPPER 


Y 


6 


MERCHANT'S 6 CHARACTER UPS ACCOUNT 
NUMBER 


TERMS 


Y 




Must be set to "SHIPPER" 


CURRENCYCODE 


N 




Must be set to "USD" 


SHIPDATE 


Y 




Ship date formatted as either: 
mm/dd/yy or mm/dd/yyyy 


SHIPMENTSERVICEOPTIONS 


N 




REQUIRED IF USING DECLARED VALUE 
OPTION 


DECLAREDVALUE 


N 




Use if using Declared Value 1 


CURRENCYCODE 


N 




Must be set to "USD" 


MONETARYVALUE 


N 




UPS Declared Value Business Rules apply. Enter 
whole integer. For example $550.00 is entered as 
"550" or "550.00" - no dollar sign. 
Declared value limits are: 
ARS = $1000.00 
Call Tag = $50,000.00 


SHIPNOTIFICATION 


N 




REQUIRED IF ANY EMAIL NOTIFICATIONS 
ARE USED 


EMAIL 


N 




Required Tag. | 


CONSIGNEEEMAIL 


N 




REQUIRED IF SENDING EMAIL 
NOTIFICATION TO CONSIGNEE 


SHIPPEREMAIL 


N 




REQUIRED IF SENDING EMAIL 
NOTIFICATION TO MERCHANT SITE - enter 
Email address at Merchant where you want email 
sent 


EMAILRETURNADDRESS 


N 




REQUIRED IF USING EMAIL -MUST BE 
VALID EMAIL ADDRESS AT MERCHANT 
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TAG 



REQUIRED? 
Y or N 



CHARACTER 
LENGTH 
MAX 



DESCRIPTION 



EMAILSUBJECT 



REQUIRED IF USING EMAIL - TEXT THAT 
WILL APPEAR IN THE EMAIL'S SUBJECT 
WINDOW 



EMAILMESSAGE 



N 



Required Tag if using any Email Notifications 



EMAILMESSAGETEXT 



ARS Example— -> 



N 



'"'is 



ill 1 "! 



S 
in* 



mill 



in. 



Call Tag Example-^ 



Sample of Actual text of email message. Example: 
<EMAILMESSAGETEXT>Your order number 
@SHIPPER_REFERENCE shipped on 
@SHIPDATE 

</EM AI LMES S AGETEXT> 
<EMAILMESSAGETEXT>via 
@SERVICEFRIENDLYNAME with tracking 
number @TRACKING_NUMBER 
</EMAI LMES S AGETEXT> 
<EMAILMESSAGETEX'I> 
Please select this link: 

fLABEL_IMAGE__FILEJJRL To view and print 
ur document. 
</EMAILMESSAGETEXT> 
<EMAILMESSAGETEX1> 
Thank you for your patronage. 
</EMAILMESSAGETEXT> 

<EMAILMESSAGETEX1>Your order number 
@SHIPPER_REFERENCE shipped on 
@SHIPDATE 

</EMAILMESSAGETEXT> 

<EMAILMESSAGETEXT>via 

@SERVICEFRIENDLYNAME with tracking 

number @TRACKING_NUMBER 

</EMAILMESSAGETEXT> 

<EMAILMESSAGETEX1> 

A UPS CALL TAG HAS BEEN ISSUED FOR 

YOUR ORDER. A UPS DRIVER SHOULD STOP 

BY IN 2-3 BUSINESS DAYS TO PICKUP YOUR 

PACKAGE. Please re-seal the package and have it 

ready for UPS to pick up. 

</EMAILMESSAGETEXT> 

<EMAILMESSAGETEXT> 

Thank you for your patronage 

</EMAILMESSAGETEXT> 



PACKAGES 



REQU IRED TAG 



PKG 



REQUIRED TAG 



PKGWEIGHT 



REQUIRED TAG 



WEIGHTUNITS 



USE "LBS" 



WEIGHTY ALU E 



ACTUAL WEIGHT IN LBS. SYSTEM WILL 
APPLY BILLABLE WEIGHT. I.E. 15.2 LBS. 
WILL BE BILLED AT 16 LBS. If using Next Day 
or 2 nd Day Air LETTER set the WEIGHTVALUE 
toO. 



DIMENSION 



Required Tag 



DIMUNITS 



IN 



DIMVALUE 



LxWxH - Enter actual package dimensions for alt 
packages where Dimensional Weight or Oversize 
applies. For all others enter dimensions as "0x0x0" 
or 

"0 0 0". 
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TAG 



REQUIRED? 
Yor N 



CHARACTER 
LENGTH 
MAX 



DESCRIPTION 



PACKAGING 



Value MUST be set to "CUSTOM" for all 
packages. For Next Day and 2 nd Day Letters the 
value must be set to "LETTER". When using 
LETTER the WEIGHTVALUE element must be 
set to "0".. 



REFERENCE 



REQUIRED TAG 



CONSIGNEEREFERENCE 



29 



CONSIGNEE'S REFERENCE 
NUMBER 



SHIPPERREFERENCE 



29 



SHIPPERS REFERENCE NUMBER 



PACKAGESERVICEOPTIONS 



REQUIRED TAG 



OVERSIZE 



N 



If package is Oversized use value "True" If not, use 
"False". 



ADDITIONALHANDLING 



N 



4 



If Additional Handling is Required use value 
"True" If not, use "false". 



CALLTAG 



REQUIRED IF USING CALL TAG SERVICE 



Required if using call tag service. 

Value is "True" or "I" if using Call Tag. Set to 
"FALSE" if ARS. 



CALLTAG FLAG 



CALLTAGDESCRIPTION 



N 



3# 



Pi, 



REQUIRED IF USING CALL TAG SERVICE - 
WILL CONTAIN DESCRIPTION OF GOODS 
BEING RETURNED 



RETURNDELIVERY 



REQUIRED TAG 



RETURNDELIVERYFLAG 



H' 



For ARS value is set to "TRUE" - for Call Tags 
value is set to "FALSE" 



RETURNDELIVERYDESCRIPTION 



35 



REASON FOR RETURN 



LABELFORMAT 



MUST be included if ARS is used. Value must 
be: TANDATA_UPS_MAXICODE_US 
DOMESTIC. STANDARD 



SHIPMENTSERVICE 



REQUIRED TAG 



SCS 



PACKAGE SERVICE LEVEL 
Next Day Air = 
"TANDATA_UPS.UPS.NDA" 
2 nd Day Air = 

"TANDATA_UPS.UPS.2DA" 
3 Day Select = 

"TANDATA_UPS.UPS.3DA" 
Ground = 

"TANDATA_UPS.UPS.GND" 

NOTE: these are the ONLY service levels available 
for UPS Returns on the Web. 



CLOSEOUTMODE 



MUST BE SET TO "1" or "TRUE" 



PACKAGEDETAIL 



MUST BE SET TO "1" or "TRUE" 
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XML Shipment Request 

Example with explanations of fields: 

<?xml version-" 1.0" encoding="UTF-8"?> 

<! — Prolog -XML Doctype name and DTD referenced 

<!DOCTYPE SHIPMENTREQUEST SYSTEM " http://www.upsreturnservices.corn/dtd/shipreqtest.dtd "> 

<!-Opening tag-> 

<SHIPMENTREQUEST> 

<! -Opening Login tag-> 

<LOGIN> 

<! -Login ID and Password assigned to you-> 
<LOGiNID>UPSTEST</LOGINID> 
<PASSWORD>UPSTEST</PASSWORD> 
</LOGIN> ^jll). 
<!-Start of DEF ATTRIBUTES Section— > { 
<DEFATTRJBUTES> a* 
<!--Start of CONSIGNEE Elements-> <{| 1 , 
<CONSIGNEE> M|JJJ|' 

<COMPANY>BRIAN DEI(^AN<cM}MPANY> 
<ADDRESS1>75 SMITH Stjf|ki)pRESSl> 
<CITY>FAmiNGD^E</ClBfjBJI> 
<STATEPROVIN(3ipf |</ST^irEPROVINCE> 
<POSTALCODE>l 17^||t||J0STALCODE> 

ITED STATES</COUNTRYSYMBOL> 



<COUNTRY8Jf|MBO T u 



tYSffjME 

</CONSIGNEE> %\U ^\ 
<SHIPPERJNFO> "| 
<!--Usingthe6Cl 



icter UPS Account Number Assigned to you Returns on the WEB.— 



<SHIPPER>123456</SHIPPER> 
</SHIPPERINFO> 
<TERMS>SHIPPER</TERMS> 

<!-SHIPDATE MUST BE FORMATTED mm/dd/yy or mrn/dd/yyyy-> 

<SHIPDATE>07/27/00</SHlPDATE> 

<!— Shipment service options can include Declared Value — > 

<SHIPMENTSERVICEOPTIONS> 

<!-CURRENCYCODE must always be set to USD-> 
<DECLAREDVALUE> 

<CURRENCYCODE>USD</CURRENCYCODE> 
<MONETARYVALUE>220.00</MONETARYVALUE> 
</DECLAREDVALUE> 
</SHIPMENTSERVICEOPTIONS> 
<SHIPNOTIFICATION> 
<EMAIL> 

<!~CONSIGNEEEMAILCONSIGNEEEMAIL INDICATES THE EMAIL 
ADDRESS OF MERCHANT'S CUSTOMERS 

<CONSIGNEEEMAILCONSIGNEEEMAIL>ELI3BXD@UPS.COM</CONSIGNEEEMAILCONSIGNE 
EEMAIL> 

<!-SHIPPEREMAIL indicates the Email Address at the merchant where 

notification will be sent.— > 

<SHIPPEREMAIL>bdeignan@UPS.COM</SHIPPEREMAIL> 
<!—EMAILRETURN ADDRESS must be a valid email address at merchant. This is the address that an email will be 
sent to if a user chooses "Reply" to their original email notification.~> 
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<EMAILRETURNADDRESS>ELI3BXD@UPS.C0M</EMAILRETURNADDRESS> 

<!--EMAILSUBJECT is the text that will appear in the "Subject" window of all 

email notifications.— > 

<EMAILSUBJECT>YOUR RETURNED ORDER AT 

XYZ.COM</EMAILSUBJECT> 

<EMAILMESSAGE> 

<!~EMAILMESSAGETEXT will contain the text and variables that merchant wants to appear in all email 
notifications~> 

<EMAILMESSAGETEXT>Your order number ©SHIPPER REFERENCE shipped on 
@SHIPDATE</EMAILMESSAGETEXT> 

<EMAILMESSAGETEXT>via @SERVICEFRIENDLYNAME with 
tracking number @TRACKING_NUMBER< / EMAILMESSAGETEXT> 

<EMAILMESSAGETEXT>Please select this link: @LABEL_IMAGE_FILE_URL To view and print your 
document</EMAILMESSAGETEXT> ^ 

<EMAILMESSAGE™Wl>Thank you for your 
patronage</EMAILMESSAGETEXT> f| M|h 

</EMAILMESSAGE> <(j J 1 ' t M> 
</EMAIL> %# 

in,, 

<PACKAGES> 4\r\\\ 
<PKG> Hllft, 

<PKGWEI(^PM I. 

<WErgto||N 

<WEIGIWVALUE>12.2<yWEIGHTVALUE> 
</PKGWEIGHT> 

<!-DIMUNITS always set to IN and actual package dimensions in Dimvalue--> 
<DIMENSION> 

<DIMUNITS>IN</DIMUNITS> 

<!-Height, Width and Length dimensions. Entered either as "HxWxL" or "H W 



</SHIPNOTIFICATION> 



</DEFATTRIBUTES> ui 
<!--Start of the PACKAGES Elements--^ UlP 

dm % 



<!~Package weight units always set to ^gjj|VEI(3t|jj;vALUE will be package actual weight. -> 



<DIMVALUE>2 2 5</DIMVALUE> 
<DIMENSION> 

<!-PACKAGING value MUST BE set to CUSTOM-> 
<PACKAGING>CUSTOM</PACKAGING> 

<!-REFERENCE elements contain whatever reference fields the merchant deems 



applicable-> 



<REFERENCE> 

<CONSIGNEEREFERENCE>123556</CONSIGNEEREFERENCE> 
<SHIPPERREFERENCE>UUH6754</SHIPPERREFERENCE> 
</REFERENCE> 

<!-PACKAGE SERVICE OPTIONS - Oversize is either TRUE or FALSE, Additional Handling is either TRUE or 
FALSE. CALLTAG is either TRUE or FALSE. CALLTAG will ONLY be TRUE if ARS is not used. 
CALLTAGDESCRIPTION is where the description of the goods being returned is entered. -> 
<PACKAGESERVICEOPTIONS> 

<OVERSIZE>FALSE</OVERSIZE> 

<ADDITIONALHANDLING>FALSE</ADDITIONALHANDLING> 
<!--CALLTAGDELIVERYFLAG will be set to TRUE for CALL TAG and 

FALSE for ARS~> 

<CALLTAG> 

<CALLTAGFLAG>TRUE</CALLTAGFLAG> 
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<CALLTAGDESCRIPTION>15 BLUE 

WIDGETS</CALLTAGDESCRIPTION> 

</CALLTAG> 

<!--RETURNDELIVERYFLAG will be set to TRUE for ARS and FALSE for 

Call Tag.--> 

<!-RETURNDELIVERYDESCRIPTION will contain the reason for return for 

ARS. --> 

<RETURNDELIVERY> 

<RETURNDELIVERYFLAG>FALSE</RETURNDELIVERYFLAG> 

<RETURNDELIVERYDESCRIPTION>NONE</RETURNDELIVERYDESCRlPTION> 
</RETURNDELIVERY> 
</PACKAGESERVICEOPTIONS> 




<LABELFORMAT>TANDATAJJPSJVlAXICODE_^ 

</PKG> X 
</PACKAGES> "||| 1 

<SHIPMENTSERVICE> ( ltj h 

<!-SCS will contain the code used foyBfeDific levels-> 



<SCS>TANDATA.UPS.UPS 



ie used foMBf%ific 1 



</SHIPMENTSERVICE> <(| P V \ > 

<!--CLOSEOUTMODE will always blm mMf --> 
<CLOSEOUTMODE> 1 <CL(^^UTM8taE> 
<!~PACKAGEDETAIL will a$Ifa$ibe set to TRUE--> 



<PACKAGEDETAII>TRUE<yP«|eBlfGEDETAIL> 
</SHIPMENTREQUEST> 
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Example of XML Document - Request ARS 

<%@ language=VBscript %> 

<% 

strPOSTURL = ,: http://www.upsreturnservices.com/sendittest.asp u 
%> 

<html> 

<FORM action="<%=strPOSTURL%>" method=post> 
<textarea name=XML id=XML rows=35 cols=80> 
<?xml version-' 1.0"?> 

<!DOCTYPE SHIPMENTREQUEST SYSTEM " http://www. upsreturn services .com/dtd/shipreqtest.dtd "> 
<!- Example of ARS issued with email notification to consignee and merchant-> 
<SHIPMENTREQUEST> 
<LOGIN> 

<LOG rNID>UPSTEST</LOGINID> 

<PASS WORD>UPSTEST</PASSWORD> ' 1 1 1 1 1 

<1 



<ADDRESS2>ACC 
<CITY>FARMINC 
<STATEPROJ 



</LOGIN> 

<DEFATTRIBUTES> a\\\* *% 

<CONSIGNEE> 'l|l||l ,> 

<COMPANY>MEDLEY , S^COMPAl|Y> 
<CONTACT>JOE SMITH^|pNTAC# 
<ADDRESS1>123 MAIN ST^pjlRESS^ 

&tingWaddress2> 

/CITY> 

, % l 4K^tATEPROVINCE> 
<POSTALG|PEl|y735%OSTALCODE> 
<COUNTRYS%^bl>UNITED_STATES</COUNTRYSYMBO^ 
</CONSIGNEE> { n\\r 
<SHIPPERINFO> 

<SHIPPER>123456</SHIPPER> 
<SHIPPERINFO> 
<TERMS>SHIPPER</TERMS> 
<CURRENCYCODE>USD</CURRENCYCODE> 
<SHIPDATE>07/12/00</SHIPDATE> 
<SHIPMENTSERVICEOPTIONS> 
<DECLAREDVALUE> 

<CURRENCYCODE>USD</CURRENCYCODE> 
<MONETARYVALUE>0</MONETARYVALUE> 
</DECLAREDVALUE> 
</SHIPMENTSERVICEOPTIONS> 
<SHIPNOTIFICATION> 
<EMAIL> 

<CONSIGNEEEMAIL>ELI3BXD@UPS.COM</CONSIGNEEEMAIL> 
<SHIPPEREMAIL>JOE@XYZ.COM</SHIPPEREMAIL> 

<EMAILRETURNADDRESS>BDS@XYZ.COM</EMAILRETURNADDRESS> 

<EMAILSUBJECT>Your return authorization.</EMAILSUBJECT> 
<EMAILMESSAGE> 

<EMAILMESSAGETEXT> YOUR ORDER NUMBER 
@SHIPPER_REFERENCE SHIPPED ON @SHIPDATE</EMAILMESSAGETEXT> 

<EMAILMESSAGETEXT>VIA @SERVICEFRIENDLYNAME 
WITH TRACKING NUMBER @TRACKING_NUMBER.</EMAILMESSAGETEXT> 

<EMAILMESSAGETEXT>PIease select this image link: 
@LABELJMAGE_FILE_URL to view and print your document.</EMAILMESSAGETEXT> 
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<EM AI LMESS AGETEXT>TH ANK YOU FOR USING MEDLEY'S 
ONLINE RETURN SERVICE.</EMAILMESSAGETEXT> 

</EMAILMESSAGE> 
<!— valid variables are : 

For labels but NOT documents 

@LABELJMAGE_FILE_NAME 
@LABEL_IMAGE_FILE_URL 
@SHIPPER_REFERENCE 
@SHIPDATE 

@SERVICEFRIENDLYNAME 
@TRACKING_NUMBER 
For Documents but NOT Labels 
@DOC_FILE_NAME 
@DOC_FILE_URL 
@DOC FRIENffiLYNAME 

</EMAIL> |t % 

</SHIPNOTIFICATION> «{| * f l V 

</DEFATTRIBUTES> % {'* 

<PACKAGES> tt\u, \, 



<PKG> WMliu 
<PKGWEIGHT> n %tWV' 

<WEIGH-B|P: |S>LB3FAVEIGHTUNITS> 
<WEIGHT% ttimj 2. 1 </WEIGHTVALUE> 

<DIMENSI(SK> 

<DINfOhU$p 

<DIMVAt|luE>OXOXO<^DIMVALUE> 
<DIMENSION> 

<PACKAGING>CUSTOM</PACKAGING> 
<REFERENCE> 

<CONSIGNEEREFERENCE> 1 1 22</CONSIGNEEREFERENCE> 
<SHIPPERREFERENCE>PO 123</SHIPPERREFERENCE> 
</REFERENCE> 

<PACKAGESERVICEOPTIONS> 

<OVERSIZEx/OVERSIZE> 

<ADDITIONALHANDLINGXADDITIONALHANDLING> 
<CALLTAG> 

<CALLTAGFLAG>FALSE<CALLTAGFLAG> 
<CALLTAGDESCRIPTION></CALLTAGDESCRIPTION> 
</CALLTAG> 
<RETURNDELIVERY> 

<RETURNDELIVERYFLAG>TRUE</RETURNDELIVERYFLAG> 
<RETURNDELIVERYDESCRIPTION> WRONG COLOR 
</RETURNDELIVERYDESCRIPTION> 

</RETURNDELIVERY> 
</PACKAGESERVICEOPTIONS> 
<LABELFORMAT>TANDATA_UPS^MAXICODE^US_DOMESTIC.STANDARD<VLABELFORMAT> 
</PKG> 
</PACKAGES> 
<SHIPMENTSERVICE> 

<SCS>TANDATAJJPS.UPS.GND</SCS> 
</SHIPMENTSERVICE> 
<CLOSEOUTMODE> 1 </CLOSEOUTMODE> 
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<PACKAGEDETAIL>TRUE</PACKAGEDETAIL> 
</SHIPMENTREQUEST> 
</textarea><BR> 

<input type=submit value="SEND"> 

<input type=hidden value="http://207.16.70.48/c!ient/saveorder.asp n name- 'RETURN URL "> 

<input type=hidden name -'MERCHANTORDERNUMBER" value^'TOlM^ 

</form> 

</html> 




e 
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Example of XML Document - Request Call Tag 



-in 

et 



in, 



r w.upsretlimservicesxom/dtd/shipreqtest.dtd "> 
t jf^nsignee and merchant— > 

ORE» 



<%@ language=VBscript %> 

<% 

strPOSTURL = "http://www.upsreturnservices.com/sendittestasp" 
%> 

<html> 

<FORM action="<%=strPOSTURL%>" method=post> 
<textarea name=XML id=XML rows=35 cols=80> 
<?xml version-' 1.0"?> 

<!DOCTYPE SHIPMENTREQUEST SYSTEM "fettpi 
<!-- Example of CALL TAG issued with email notiflcatifc 
<SHIPMENTREQUEST> All 
<LOGIN> "\k 
<LOGINID>UPSTESTfj/LOGr , 
<PASSW0RD>UPS^||Pt}^AS5 
</LOGIN> 

<DEFATTRIBUTES> 

<CONSIGNEE> 

<COMP AN Y>MEDLE Y'S</COMP ANY > 
<CONTACT>JOE SMITH</CONTACT> 
<ADDRESS1>123 MAIN ST</ADDRESS1> 
<ADDRESS2>RETURNS DEPT</ADDRESS2> 
<CITY>FARMINGDALE</CITY> 
<STATEPROVINCE>NY</STATEPROVINCE> 
<POSTALCODE>l 1735</POSTALCODE> 

<COUNTRYSYMBOL>UNITED_STATES</COUNTRYSYMBOL> 
</CONSIGNEE> 
<SHIPPERINFO> 

<SHIPPER>123456</SHIPPER> 
</SHIPPERINFO> 
<TERMS>SHIPPER</TERMS> 
<CURRENCYCODE>USD</CURRENCYCODE> 
<SHIPDATE>07/12/00</SHIPDATE> 
<SHIPMENTSERVICEOPTIONS> 

<DECLAREDVALUE> 

<CURRENCYCODE>USD</CURRENCYCODE> 
<MONETARYVALUE>550</MONETARYVALUE> 

</DECLAREDVALUE> 
</SHIPMENTSERVICEOPTIONS> 
<SHIPNOTIFICATION> 

<EMAIL> 

<CONSIGNEEEMAIL>ELI3BXD@UPS.COM</CONSIGNEEEMAIL> 
<SHIPPEREMAIL>JOE@XYZ.COM</SHIPPEREMAIL> 
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<EMAILRETURNADDRESS>BDS@XYZ.COM</EMAILRETURNADDRESS> 

<EMAILSUBJECT>XYZ.COM will have you package picked up 

short!y</EMAILSUBJECT> 

<EMAILMESSAGE> 

<EMAILMESSAGETEXT> YOUR ORDER NUMBER 
@SHIPPER_REFERENCE SHIPPED ON @SHIPDATE</EMAILMESSAGETEXT> 

<EMAILMESSAGETEXT>VIA @SERVICEFRJENDLYNAME 
WITH TRACKING NUMBER @TRACKING_NUMBER </EMAILMESSAGETEXT> 

<EMAILMESSAGETEXT>A UPS CALL TAG HAS BEEN ISSUED 
FOR YOUR ORDER. UPS WILL BE BY TO PICK UP YOUR PACKAGE IN 2 TO 3 BUSINESS 
DAYS.</EMAILMESSAGETEXT> 

<EMAILMESSAGETEXT>THANK YOU FOR USING MEDLEY'S 
ONLINE RETURN SERVICE.</EMAILMESSAGETEXT> 

</EMAILMESSAGE> ,|h. 
</EMAIL> MjL 
</SHIPNOTIFICATION> (| H|u 

</DEFATTRIBUTES> <(| . V 

<PACKAGES> Mil! 
<PKG> <.„ 



<PKGWEIGHT> 

<WEIGHTlMTS>LyR)%EIGHTUNITS> 



<WEIGHTj||PfljlJE> 



</PKGWEIGHT> 
<DIMENSIQjIti|{ 



E>12l k/WEIGHTVALUE> 



<DT9|P^iKS>IN<A3IMUNITS> 
<DIM%JbE>0X0X0<^)IMVALUE> 

</dimension>"I" 

<packaging>custom</packaging> 
<reference> 

<consigneereference> 1 1 22</consigneereference> 
<shipperreference>jkl998j765</shipperreference> 
</reference> 

<packageserviceoptions> 
<oversize></oversize> 

<additionalhandling></additionalhandling> 

<CALLTAG> 

<CALLTAGFLAG>TRUE</CALLTAGFLAG> 
<CALLTAGDESCRIPTION>WRONG COLOR 

SHIPPED</CALLTAGDESCRIPTION> 

</CALLTAG> 
<RETURNDELIVERY> 

<RETURNDELIVERYFLAG>FALSE</RETURNDELIVERYFLAG> 

<R£TURNDELIVERYDESCRIPTION> WRONG 
ORDER</RETURNDELIVERYDESCRIPTION> 

</RETURNDELIVERY> 
</PACKAGESERVICEOPTIONS> 

<yPKG> 
</PACKAGES> 
<SHIPMENTSERVICE> 

<SCS>TANDATA_UPS.UPS.GND</SCS> 
</SHIPMENTSERVICE> 
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<CLOSEOUTMODE> 1 </CLOSEOUTMODE> 
<PACKAGEDETAIL>TRUE</PACKAGEDETAIL> 
</SHIPMENTREQUEST> 

</textarea><BR> 

<input type=submit value="SEND"> 

<input type=hidden value="http://207.16.70.48/client/saveorder.asp n name="RETURNURL"> 

<input type=hidden name ="MERCHANTORDERNUMBER" vaiue="P0123 M > 

</form> 

</html> 



Example of XML Document - Request ARS FOR NDA LETTER 

<%@ language=VBscript %> /» 



<LOGIN> *Hh| m 

<LOGrNID>UPSTEST</LOGINID3i|jIr f 

<PASSWORD>UPSTEST</PASSWORD> 
</LOGrN> 

<DEFATTRIBUTES> 
<CONSiGNEE> 

<COMPANY>MEDLEY'S</COMPANY> 
<CONTACT>JOE SMITH</CONTACI> 
<ADDRESS1>123 MAIN ST</ADDRESS1> 
<ADDRESS2>RETURNS DEPT</ADDRESS2> 
<CITY>FARMINGDALE</CITY> 
<STATEPROVINCE>NY</STATEPROVINCE> 
<POSTALCODE>l 1735</POSTALCODE> 

<COUNTRYSYMBOL>UNITED_STATES</COUNTRYSYMBOL> 
</CONSlGNEE> 
<SHIPPER1NF0> 

<SHIPPER> 1 23456</SHIPPER> 
</SHIPPERINFO> 
<TERMS>SHIPPER</TERMS> 
<CURRENCYCODE>USD</CURRENCYCODE> 
<SHIPDATE>07/12/00</SHIPDATE> 
<SHIPMENTSERVICEOPTK)NS> 

<DECLAREDVALUE> 

<CURRENCYCODE>USD</CURRENCYCODE> 
<MONETARYVALUE>0</MONETARYVALUE> 

</DECLAREDVALUE> 
</SHlPMENTSERVlCEOPTIONS> 
<SHLPNOTlFICATION> 
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<EMAIL> 

<CONSIGNEEEMAIL>ELI3BXD@UPS.COM</CONSIGNEEEMAIL> 
<SHIPPEREMA!L>JOE@XYZ.COM</SHIPPEREMAIL> 
<EMAILRETURNADDRESS>BDS@XYZ.COM</EMAILRETURNADDRESS> 
<EMAILSUBJECT>Your return authorization.</EMAlLSUBJECT> 
<EMAILMESSAGE> 

<EMAILMESSAGETEXT> YOUR ORDER NUMBER @SHIPPER_REFERENCE SHIPPED 
ON @SHIPDATE</EMAlLMESSAGETEXr> 

<EMAILMESSAGETEXT>VIA @SERVICEFRIENDLYNAME WITH TRACKING 
NUMBER @TRACKING_NUMBER.</EMAILMESSAGETEXT> 

<EMAILMESSAGETEXT>Please select this image link: @LABEL_IMAGE_ FILE URL to 
view and print your document. </EMAILMESSAGETEXT> 

<EMAILMESSAGETEXT>THANK YOU FOR USING MEDLEY'S ONLINE RETURN 
SERVICE.</EMAILMESSAGETEXT> 
</EMAILMESSAGE> 
<!— valid variables are : 

For labels but NOT documents 

@LABEL_IMAGE_FILE_NAME 
@LABEL_IMAGE_FILE_URL 
@SHIPPER_REFERENCE A 
@SHIPDATE 
@SERVICEFRIENDL^ 
@TRACKING_NUME 
For Documents but NOT LaB 
@DOC_FILEJvU 
@DOC_FILE_L)l 
@DOC_FRIENDtfi 

— > 
</EMAIL> 
</SHIPNOTIFICATION> 
</DEFATTRlBUTES> 
<PACKAGES> 
<PKG> 

<PKGWEIGHT> % . 

<WEIGHTUNITS>LBS<7WEIGHTUNITS> 
<WEIGHTVALUE>0</WEIGHTVALUE> 
</PKGWEIGHT> 
<DIMENSION> 

<DIMUNITS>IN</DIMUNITS> 
<DIMVALUE>OXOXO<yDIMVALUE> 
</DIMENSION> 

<PACKAGING>LETTER</PACKAGING> 
<REFERENCE> 

<CONSIGNEEREFERJENCE> 1 1 22</CONSIGNEEREFERENCE> 
<SHIPPERREFERENCE>JKL998J765</SH1PPERREFERENCE> 
</REFERENCE> 

<PACKAGESERVICEOPTIONS> 
<OVERSIZE></OVERSIZE> 

<ADDITIONALHANDLING></ADDITIONALHANDLING> 
<CALLTAG> 

<CALLTAGFLAG>FALSE</CALLTAGFLAG> 

<CALLTAGDESCRIPTION></CALLTAGDESCRlPTION> 
</CALLTAG> 

<RETURNDEL1VERY> 
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<RETURNDELIVERYFLAG>TRUE</RETURNDELIVERYFLAG> 
<RETURNDEL1VERYDESCRIPTION>OBTAINED APPROVALS ON CONTRACT 
</RETURNDELIVERYDESCRIPTION> 
</RETURNDELIVERY> 
</PACKAGESERVICEOPT10NS> 

<LABELFORMAT>TANDATA_UPS_MAXICODE_US_DOMESTIC.STANDARD</LABELFORMAT> 

</PKG> 
</PACKAGES> 
<SHIPMENTSERVfCE> 

<SCS>TANDATA_UPS.UPS.NDA</SCS> 
</SHIPMENTSERVICE> 
<CLOSEOUTMODE> 1 </CLOSEOUTMODF> 
<PACKAGEDETAIL>TRUE</PACKAGEDETAIL> 




</textarea><BR> u Mjjj 

<input type=submit value="SEND"> ih 

<input type=hidden value= M http://207. 16.70 48/client/saveord^tt^ name= H RETURNURL"> 
<input type=hidden name - 'MERCHANTORDERNUjWBER" va%f "PO!23"> 



</form> 
</html> 
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3.6 Shipment Response 

Response DTD 

Upon receiving a successful REQUEST, UPS Returns on the Web will return a RESPONSE 
that conforms to the following DTD: 

?xml version-' L0" encoding-"UTF-8"?> 

<!ELEMENT SHIPMENTRESPONSE (RESPONSE, RATEDSHIPMENT)> 

<! ELEMENT RESPONSE (TRANSACTIONREFERENCE, RESPONSESTATUSCODE, 
RESPONSESTATUSDESCRIPTION)> 

<!ELEMENT TRANSACTIONREFERENCE (CUSTOMERC^NTEXTy^PCIVERSION)> 
<!ELEMENT CUSTOMERCONTEXT (#PCDATA)> 



I 



Hii. 



<! ELEMENT XPCIVERSION (#PCDATA)> 
<!ELEMENT RESPONSESTATUSCODE (#^{{l?i|lrA)> 
<!ELEMENT RESPONSESTATUSD^|fi^^TIONf^PCDATA)> 

<! ELEMENT RATEDSHIPMENT (ERR(^|f ||lIPMENTSERVICE, BILLINGWEIGHT, TOTALCHARGES, 
TRANSPORTATIONCHARGES, SERVICE3DPTIONSCHARGES, DELIVER YINFO, RATEDPACKAGE)> 

<!ELEMENT ERROR (ERRORCODE, ERRORDESCRIPTION)> 

<! ELEMENT ERRORCODE (#PCDATA)> 

<!ELEMENT ERRORDESCRIPTION (#PCDATA)> 

<!ELEMENT SHIPMENTSERVICE (SCS, DESCRIPTION)> 

<!ELEMENT SCS (#PCDATA)> 

<!ELEMENT DESCRIPTION (#PCDATA)> 

<!ELEMENT BILLINGWEIGHT (WEIGHTUNITS, WEIGHTVALUE)> 
<!ELEMENT WEIGHTUNITS (#PCDATA)> 
<!ELEMENT WEIGHTVALUE (#PCDATA)> 

<!ELEMENT TOTALCHARGES (CURRENCYCODE, MONETARYVALUE)> 
<!ELEMENT CURRENCYCODE (#PCDATA)> 
<! ELEMENT MONETARY VALUE (#PCDATA)> 

<! ELEMENT TRANSPORTATIONCHARGES (CURRENCYCODE, MONETARYVALUE)> 
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<! ELEMENT SERVICEOPTIONSCHARGES (CURRENCYCODE, MONETARYVALUE)> 

<! ELEMENT DELIVERYINFO (SHIPDATE, GUARANTEEDDAYSTODELIVERY, 

SCHEDULEDDELIVERYTIME, 

ARRIVEDATE)> 

<! ELEMENT SHIPDATE (#PCDATA)> 

<!ELEMENT GUARANTEEDDAYSTODELIVERY (#PCDATA)> 
<! ELEMENT SCHEDULEDDELIVERYTIME (#PCDATA)> 
<! ELEMENT ARRIVEDATE (#PCDATA)> 

<!ELEMENT RATEDPACKAGE (PKGERROR, PACKAGETOTjp CHARGES, PACKAGEBASECHARGES, 
PACKAGESERVICEOPTIONSCHARGES, TRACKINGNUMBER, KlfarERENCE, PKG WEIGHT, 
BILLINGWEIGHT, LABELREOUESTINFO, LABELURLirf W , % 



<!ELEMENT 



, LABELREQUESTINFO, LABELURL)(f P 

c %t 

I ,„ 

LABELSTATUS (ERRORCOI^yfeflORlii »SCRIPTION)> 



<!ELEMENT PKGERROR (ERRORCODE, ERRO 
EMAILSTATUS)> 



CRIPT^J, 
h ' 



LABELSTATUS, HTMLSTATUS, 
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Shipment Response Elements - Field Explanations 

The following table describes each of the elements contained in a shipment response that will be 
sent to the RETURNURL specified in the request. 



TAG 


VALUE 


DESCRIPTION 


SHIPMENTRESPONSE 




Opening TAG 


RESPONSE 




Opening TAG 


TRANSACTIONREFERENCE 




Opening TAG 


CUSTOMERCONTEXT 


Local Mode Using 
TanData 


System Generated Header 


XPCIVERSION 


1.0 


System Generated Header 


RESPONSESTATUSCODE 




A value of 0 indicates success. A value of 2 indicates an 
error. 


RESPONSESTATUSDESCRIPTION 




Success or error. 


RATEDSHIPMENT 




Jfk thing TAG 


ERROR 




Wing TAG 


ERRORCODE 




A va U$^f 2 indicates an error. 


ERRORDESCRIPTION 


NO ERROR 'M K f 


fcAny possible error descriptions will appear here. 


SHIPMENTSERVICE 




^Opening TAG 


SCS 

i 


'"III K 
ill 


Shipper Service Level Code 
Possible values are: 
Next Day Air = 
"TANDATA UPS.UPS.NDA" 
2 nd Day Air = 

"TANDATAUPS . UPS . 2DA" 
3 Day Select = 

«T AMH ATA ¥ TDO 1 IDC ^T^O" 

1 AINDA 1 A_l)ri). Urb. JDb 
Ground = 

"TAMnATA i ip<s t ipq r.wn" 






T TP^ Prif*nHlv Nam** nf" thic trun^arHnn 






Hnpnino TTAft 




LDO 




WFIOHTVAI TIF 




Rillnhlp wpiaht in T h<; 

UllluUlv WVlgllt 111 J_>LFO. 






Oneninp TAG 




USD 




IVf ONFT A R YV A 1 .1 IF 




Value of Transnortation Charges + Service ontion charges 
Example: 3.02 


TRANSPORT ATIONCHARGES 




Opening TAG 


CURRENCYCODE 


USD 




MONETARYVALUE 




UPS Published Service Charge based on weight and zone. 
Example: 3.02 


SERVICEOPTIONCHARGES 




Opening TAG 


CURRENCYCODE 


USD 




MONETARYVALUE 




UPS Published Accessorial Charges such as Declared 
Value and Call Tag. 


DELIVERYINFO 




Opening TAG 


SHIPDATE 




Mm/dd/yy 


GUARANTEEDDAYSTODELIVERY 


NONE 


Not Applicable to ARS or Call Tag 


SCHEDULEDDELIVERYTIME 


NONE 


Not Applicable to ARS or Call Tag 


ARRIVEDATE 


NONE 


Not Applicable to ARS or Call Tag 


RATEDPACKAGE 




Opening TAG 


PKGERROR 




Opening TAG 


ERRORCODE 


0 


A value of 0 indicates success. 


ERRORDESCRIPTION 


NO ERROR 


Any Package Rating Errors 


LABELSTATUS 




Opening TAG 
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TAG 



VALUE 



DESCRIPTION 



ERRORCODE 



A value of 0 indicates success. 



ERRORDESCRIPTION 



NO ERROR 



Any Label Creation Errors 



HTMLSTATUS 



Opening TAG 



ERRORCODE 



A value of 0 indicates success. 



ERRORDESCRIPTION 



NO ERROR 



Any HTML Errors 



EMAILSTATUS 



Opening TAG 



ERRORCODE 



A value of 0 indicates success. 



ERRORDESCRIPTION 



NO ERROR 



Any Email(SMTP) erro rs 



PACKAGETOTALCHARGES 



Opening TAG 



CURRENCYCODE 



USD 



MONETARYVALUE 



Value of Transportation Charges + Service option charges. 
E xample: 3.02 



PACKAGEBASECHARGES 



Opening TAG 



CURRENCYCODE 



USD 



MONETARYVALUE 



^Published Service Charge based on weight and zone. 
pie: 3.02 




PACKAGESERVICEOPTIONSCHARGES 



TAG 



CURRENCYCODE 



USD 



J UPS Published Accessorial Charges such as Declared 
Value and Call Tag. 



MONETARYVALUE 



TRACKINGNUM BER 



001 



it 



racking Number assigned to this ARS/ Call Tag 
transaction 



REFERENCE 



III 



Opening TAG 



SHIPPERREFERENCE 



it 



Shipper's Reference number from Request File 



CONSIGNEEREFERENCE 



Consignee's Reference number from Request File 



PKGWEIGHT 



Opening TAG 



WEIGHTUNITS 



WEIGHTVALUE 



Hi 



BILLINGWEIGHT 



Actual Weight captured from SHIPMENTREQUEST. 
Example 0.2500 



Opening TAG 



WEIGHTUNITS 



LBS 



WEIGHTVALUE 



Billable Weight. Example 1.0000 



LABELREQUESTINFO 



Opening TAG 



SHIPPER 



123456 



Shipper's UPS Account Number from Re qu est File 



scs 



TANDATA UPS. 
UPS.GND 



Carrier Service Level Code 
See SCS reference above 



SC 



TANDATA_UPS. 
UPS 



Carrier Code 



MSN 



Master Sequential Number generated by Returns 
Application. 



BUNDLEID 



Bundle ID Number generated by Returns Application. 



PACKAGELISTID 



Package List ID Number generated by Returns 
Application. 



POSTALCODE 



92562-0000 



Customer's Postal Code 



RETURNDELIVERY 



Opening TAG 



RETURNDELIVERYFLAG 



TRUE 



Value from Request File -should always be TRUE 



DIMENSION 



Opening TAG 



DIMUNITS 



IN 



'Inches" 



DIMVALUE 



Length x Width x Height of Package - from Request File 



PACKAGING 



Packaging Value for Request File. Acceptable values are 
'Custom" and Letter" 



LABELURL 



URL to post label image to. For example: 
http://150.105.32.66/server/x.com/links/4071.html 
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XML SHIPMENT RESPONSE 
Example with explanations of fields: 

<?xml version= ,, 1.0" encoding= ,, UTF-8 ,, ?> 

<! -Prolog- XML Doctype name and DTD reference--> 

<!DOCTYPE SHIPMENTRJESPONSE SYSTEM "D:\DTD\dtd_responsel3 10.dtd"> 

<SHIPMENTRESPONSE> 
<RESPONSE> 

<!~System Generated Headers-> 
<TRANSACTIONREFERENCE> 

<CUSTOMERCONTEXT>Local Mode Using TanData</CUSTOMERCONTEXT> 

<XPCIVERSION> 1 .(X/XPCI VERSION> 
</TRANSACTIONREFERENCE> - 
<!-RESPONSESTATUSCODE of 0 indicates sucdj|js~> 
<RESPONSESTATUSCODE>0<mESPONSE^R%SCODE> 
<!-Success message or error codes appear <{h. 

<RESPONSESTATUSDESCRIPTION>S^{k^^RESPDNSESTATUSDESCRIPTION> 
</RESPONSF> 

<RATEDSHIPMENT> 
<ERROR> 

<!-ERRORCODE 



<ERRORCq 





I l^tessi J : s< i error t< *J di played in ERRi -RD1 SCRJPTION- 



Charges-> 



It' 

DRCODE> 

<ERRORDE^RlTE^ON>No error</ERRORDESCRIPTION> 
</ERROR> 

<!-SCS indicates Carrier Service Level.--> 
<SHIPMENTSERVICE> 

<SCS>TANDATA_UPS.UPS.GND</SCS> 

<DESCRIPTION>UPS Ground</DESCRIPTION> 
</SHIPMENTSERVICE> 
<BILLINGWEIGHT> 

<WEIGHTUNITS>LBS<AVEIGHTUNITS> 

<WEIGHTVALUE>1 .0000<yWEIGHTVALUE> 
</BILLINGWEIGHT> 

<!-TotaI Charges - Transportation + Service Option Charges-> 
<TOTALCHARGES> 

<CURRENCYCODE>USD</CURRENCYCODE> 

<MONETARYV ALUE>3 ,02</MONETARYV ALUE> 
</TOTALCHARGES> 

<! -Transportation Charges calculated by weight and zone - published rates— > 
<TRANSPORTATIONCHARGES> 

<CURRENCYCODE>USD</CURRENCYCODE> 

<MONETARYVALUE>3.02</MONETARYVALUE> 
</TRANSPORTATIONCHARGES> 

<!-Service Option Charges are published rate charges for either Declared Value or Call Tag 

<SERVICEOPTIONSCHARGES> 

<CURKENCYCODE>USD</CURRENCYCODE> 

<MONETARYVALUE>0.00</MONETARYVALUE> 
</SERVICEOPTIONSCHARGES> 
<DELIVERYINFO> 
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<!-Date of Transaction (note: transactions on Web may take place over a weekend or holiday. Date reflected in 
this field will be UPS next scheduled date of service.-> 

<SHIPDATE>7/1 l/00</SHIPDATE> 

<!--Guaranteed, Scheduled and Arrive Dates do not apply to returns service.-> 

<GUARANTEEDDAYSTODELIVERY>None</GUARANTEEDDAYSTODELIVERY> 

<SCHEDULEDDELIVERYTIME>None</SCHEDULEDDELIVERYTIME> 
<ARRIVEDATE>None</ARRIVEDATE> 

</DELIVERYINFO> 

<RATEDPACKAGE> 

<!-The following are for Error reporting. Each of these levels could potentially have errors. Errors are reported at 
each level (if any).— > 

<PKGERROR> 

<ERRORCODE>0</ERRORCODE> 

<ERRORDESCRIPTION>No errdr<yERRORDESCRIPTION> 



</PKGERROR> W 
<PACKAGETOTALCHARGES> 

<CURRENCYCODE>USD</CURRENCYCODE> 

<MONETARYV ALUE>3 02^TvlONETARYV ALUE> 
</PACKAGETOTALCHARGES> 
<PACKAGEBASECHARGES> 

<CURRENCYCODE>USD</CURRENCYCODE> 

<MONETARYV ALUE>3 .02</MONETARY V ALUE> 
</PACKAGEBASECHARGES> 
<PACKAGESERVICEOPTIONSCHARGES> 

<CURRENCYCODE>USD</CURRENCYCODE> 

<MONETARYVALUE>0.00</MONETARYVALUE> 
</PACKAGESERVICEOPTIONSCHARGES> 

<!-UPS TRACKING NUMBER assigned to this transaction (ARS or Call Tag labeI).--> 

<TRACKmGNUMBER>lZ4XllX50600036835<VTRACKINGNUMBER> 

<! —REFERENCE numbers as indicated in REQUEST.--> 

<REFERENCE> 

<SHIPPERREFERENCE>ORDER: 6435 136</SHIPPERREFERENCE> 

<CONSIGNEEREFERENCE>RMA: 277754</CONSIGNEEREFERENCE> 
</REFERENCE> 
<!--Package ACTUAL weight.--> 
<PKGWEIGHT> 

<WEIGHTUNITS>LBS<yWEIGHTUNITS> 

<WEIGHTVALUE>0.2500</WEIGHTVALUE> 
</PKGWEIGHT> 
<!-Package BILLABLE weight.-> 
<BILLINGWEIGHT> 
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references--> 



<WEIGHTUNITS>LBS</WEIGHTUNITS> 

<WEIGHTVALUE> 1 .0000</WEIGHTVALUE> 
</BILLINGWEIGHT> 
<LABELREQUESTINFO> 

<SHIPPER> 1 23456</SHIPPER> 

<SCS>TANDATA_UPS.UPS.GND</SCS> 

<SC>TANDATA_UPS.UPS</SC> 

<!--MSN, BUNDLEID and PACKAGELISTID are system produced transaction 

<MSN>4071</MSN> 
<BUNDLEID>7997</BUNDLEID> 
<PACKAGELISTID>4245</PACKAGELISTID> 
<POSTALCODE>92562-0000</POSTALCODE^ 

<! — RETURNDELI VERY FLAG set to TRUE indicates ARS transaction-^ 
<RETURNDELIVERY> 

<RETURNDELIVERmf^AG>TRUE</RETURls(DELIVERYFLAG> 
<DIMENSION> (i "\ 

<DIMl|tPltpIN<^tMUNITS> 
<DIMv!%|te>0x0x0 </DIMVALUE> 
</DIME^8ION> "Ik 
" ' - ■' * ZUSTC 



<PACKAC 

</returndelive: 

</LABELREQUESjfp} 
<!-LABELURL intflkt 
<LABELUR | yflbttp://l5 
</RATEDPACKAG8fj I \ 
</'RATEDSHIPMENT> %\M 
</SHIPMENTRESPONSE> "I" 



rOM</PACKAGING> 



tion where label image is located — > 
'.32.66/Server/xxonVLinks/407 1 ,htmKLABELURL> 
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3.6 Error Codes 



Error Code Listing 

The following is a list of error codes that could be returned in the SHIPMENTRESPONSE: 

Select Case (code) 
Case'T* 

ErrorMessage = "No Error" 
ERROR CODES 600-699 

Case "608" (J 
ErrorMessage = "Document Not Recognized." fllllP' 



ErrorMessage = "Invalid Document Type. Verify Label Format and Send LabelRequest." 
Case "2402" 

ErrorMessage = "Invalid Weight Units for specified Merchant 
Profile" 

Case "2403" 

ErrorMessage = "Invalid Currency Units for specified 
Merchant Profile" 

Case "2404" 

ErrorMessage = "Insufficient Consignee information" 
Case "2405" 

ErrorMessage = "Invalid Shipper" 
Case "2425" 

ErrorMessage = "Not generated due to previous error" 
Case "2426" 

ErrorMessage = "HTML Link File not generated due to unknown error" 
Case "2427" 

ErrorMessage = "Label and/or Label Image File not generated due to unknown error" 
Case "2428" 
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ErrorMessage = "Not Requested" 
Case "2429" 

ErrorMessage = "Email Message not sent due to unknown SMTP error.' 



ERROR CODES 2430-2475 
Case "2431" 

ErrorMessage = "Partial Success. See individual package details." 
Case "2435" 

ErrorMessage = "No Label available for this carrier service." 



ErrorMessage = "No Shipment Data Received." ^\mh 

► 1 



Case "2436" 
ErrorMessa^ 

Case "2437" iU H|k 

ErrorMessage = "Unable to Process Request. Insufficient DataM|||j^ 
Received." ^ \. 

Case "2440" m W^' 

ErrorMessage = "Partial Success. See IndividuaiBaM^r CocWl v for Details." 

Case "2441" 

ErrorMessage = "Invalid Login ID. Veflllafej ID with 
System Administrator." 

Case "2442" 

ErrorMessage = "Value for NUMTX is either missing or non-numeric." 
Case "2459" 

ErrorMessage = "Array Validation Error, unable to process request." 
Case "2466" 

ErrorMessage = "CLOSEOUTITEM was either not given or is not valid. Specify a valid CLOSEOUTITEM to 
continue with closeout." 

Case "2469" 

ErrorMessage = "CLOSEOUTMODE was either not given or is not valid. CLOSEOUTMODE takes the value of 
either 0 (Both), 1 (Released), or 2 (Hold)." 

Case "2471" 

ErrorMessage = "MSN was either not given or is not valid. 
Specify a valid MSN to continue." 

Case "2472" 

ErrorMessage = "Multiple Errors Occurred. See 
Individual Error Codes for Details." 
Case Else 

ErrorMessage = "Undefined Error" 
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Chapter 4 - UPS Returns on the Web Implementation 



4.1 Systems Testing Schedule 
TBD 



4.2 Information Systems Auditing 

The merchant will audit results for accuracy at each stage of deployment and verify the service 
results meet the requirements of their business rules. This verification process includes the 
scheduling of all test date and internal resources needed to conduct tests. Internally, audits 
should be performed by the merchant whenever back eiT^Bptems affecting financing, inventory, 
shipping, billing, refunds, and credits are integrated with'ir 

4 

4.3 Product Release ar 



j (Returns on the Web service. 



After the Returns on the Web service has 
schedule a 15 day and 30 day fo$fjwl|to i 

> 





ollow-up 



'■lllp meetings with the merchant after each 
Its, errors and possible corrective actions. 



The deployment representative will schedule 
test phase during the implementation td(His |u__ 

After the Returns on the Web service has^j ^Ifmplemented, the UPS deployment team will 

meefing to review post-implementation issues. 

ii 
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Chapter 5 - Post Implementation 



5.1 Merchant Questionnaire 



The deployment representative will deliver a questionnaire to be used by both the merchant, and 
if possible, the merchant's customers 30 days following implementation. The questions will 
relate to the returns process and cover site appearance and design, ease-of-use, ease of 
deployment, service reliability, quality of information, and the service offered by the UPS 
Returns on the web Deployment team. This feedback will guide UPS s e rv e to in improv ing e-the 
existing service and in develop ing future offerings. 
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Notice 

In all communications with UPS concerning this document, please refer to the XPCI version and document date located on 
the cover of this developers guide. 

Copyright 

The use, disclosure, reproduction, modification, transfer, or transmittal of this work for any purpose in any form or by any 
means without the written permission of United Parcel Service is strictly prohibited. 

^2001 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary. 

UPS eSolutions Group, Roswell, Georgia. 

Trademarks 

UPS OnLine® is a registered trademark of United Parcel Service of America. All other trademarks are the property of their 
respective owners. 
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2 Welcome to the UPS OnLirte Tools Developer s Guide. This guide explains how to integrate your e -commerce 

(D applications with the installation of UPS OnLine Tools, XML version. You may visit http://www.ec.ups.com for 

more information about Returns on the Web. 

Contents at a Glance 

• " Product Overview" provides an introduction to the UPS OnLine Tools. 

• " General Programming Information" provides essential information on integrating your e -commerce 
applications with UPS OnLine Tools. 

• " Returns on the Web" < insert description hero 

• " Customer Integration" describes the process for integration testing of your application. 
"Appendices" contains the glossary, tables, and frequently asked questions (FAQs). 

• " Bibliography" contains reference materials for this guide. 
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Product Overview 



UPS Returns on the Web 



Introduction 

Improve your online customer service with UPS Returns On The Web, available in the latest XML 
technology. This powerful UPS Online Tool provides your customers with the option to return a product 
using the same technology to which they submitted the purchase. 

You can know track a return package while making your customers return experience more pleasant. 
With UPS Returns On The Web, You Can: 

• Provide your customers with return options. 

• Improve customer service by giving your inventory management system consistent, up-to-date shipping 
information. 

Your Customers Can: 

Receive return delivery options when returning a package . 

• Receive a prepaid return label. 

• Arrange for a package pickup time. 

For more information on UPS Online Tools, including UPS Returns On The Web, please visit 
http://www.ec.ups.com . 



Tool Overview 

The " Returns on the Web" service offering is initiated by a Merchant request for an UPS Return Service. 
After the request is received and processed, the response includes shipping data and an electronic label to 
the Merchant. The Merchant can then integrate carrier data with order information and pass the label to 
their customer via e-mail, or the customer s browser. The value provided is a result of the integration of a 
Merchant's technology with UPS technology. Each solution will be slightly different according to each 
Merchant's returns business rules. 

Returns on the Web service originates from the End Consumer requesting return service using the phone or 
the Merchant's Web site. The return request will generate a label to facilitate returning the packages to the 
correct vendor. In the event the Consumer or Merchant does not receive the label or misplaces the shipment 
label, the Returns on the Web Label Recovery tool contains the ability to recover the label up to 30 days 
from the request using either the Tracking Number or the Reference Number and Shipper Number. Labels 
can be generated in real-time and be instantly ready for printing from browser or be sent via e-mail. 

This release of the tool will not support Hazardous Materials and World Wide Returns. The March release of 
Returns On The Web only facilitates returns for US 50. 
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Maintaining Your Profile 



As your e-commerce site continues to evolve, UPS OnLine Tools will evolve, too, offering more features and 
service benefits for your online customers. Once you have registered to use UPS OnLine Tools, UPS will notify 
you by e-mail of all updates and changes to the tools. It is essential that an accurate e-mail address for your 
company be maintained. You should update your profile when changes occur or responsibilities for the Tools 
shift within your company. You can also return to the UPS e-commerce site to receive the latest updated 
information about UPS OnLine Tools. 



License Agreements 



The license agreements define the necessary business obligations of both UPS and the Licensee. Some of the 
reasons your entire team should be knowledgeable of the licensing requirements include: 

• Hie license agreements have requirements that impact how programmers use and display information 
(e.g., regarding appropriate use of data and logos). 

• The license agreements are different depending on how you use the UPS OnLine Tools (e.g., as an 
end-user or third party developer). 

Usage Requirements 

As part of the UPS OnLine Tools legal agreements, users of the Tools have certain obligations that are 
spelled out within the Tools agreement and its exhibits. Regardless of the manner in which the UPS OnLine 
Tools are integrated into your specific e-commerce web site or enterprise application, you must adhere to the 
Usage Requirements of the Tools legal agreement accepted by your company. Reference your OnLine Tools 
legal agreement for complete details of bom parties' obligations. The following highlights a few of these 
usage requirements. 

Branding Requirements 

UPS should receive attribution and branding in all applications (including websites and software applications) 
that use the OnLine Tools. No End User, Third Party Developer or Access User should be permitted to use 
the OnLine Tools without providing branded recognition to UPS. Your use of the UPS logo can in no way 
imply endorsement, sponsorship or certification of your e-commerce web site or enterprise application by 
UPS. You are not allowed to use or alter the information returned by the UPS OnLine Tool in a way that 
misrepresents the information or the functionality of the tool. 
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Security Elements 



To access the UPS OnLine Tools web site and use the product, several security elements are required 
including a User ID and password, developer key and access key. Some premium tools require additional 
information and special processes in order to be implemented. Various Tool users may be licensed and 
provided access to the products in different ways. 

If you have licensed the tools through the " Get Tools" page on http://www.ec.ups.com , all security elements 
will be obtained via the web site. If you have received the tools documents through other authorized means, 
your UPS OnLine Tools contact will provide you with the security elements you need to proceed. This 
document describes the process completed via the UPS OnLine Tools web site. 

These security elements are confidential and can not be shared with other companies or third parties. 
Sharing these elements with third parties is strictly prohibited as expressed in the UPS OnLine Tools license 
agreements. 

Implementation of Security Elements 



In order to be authorized by UPS to obtain any Tool' s documentation, you or someone in your company has 
already completed the appropriate UPS OnLine Tool' s licensing process. These steps initially control your access 
to the http://www.ec.ups.com web site and technical documentation. Once you implement your Tool's enabled EC 
solution, various security elements must be provided to UPS systems at run-time. The following steps are needed 
for your software to effectively support the UPS licensing process: 

1 . Create a Tools User ID and Password. 

2. License the Tools and receive your Developer Key. 

3 . Get a XML Access Key. 

4. Build your EC solution. 

5 . Test your EC solution. 

6 . Go into production with your Tool' s enabled EC solution. 
1. Create a Tools User ID and Password. 

Customers integrating the UPS OnLine Tools must complete the registration process on the " Get Tools" 
section at http://www.ec.ups.com to obtain a User ID and Password. This ED controls access to the web site 
and allows developers to stay informed about the latest OnLine Tools updates and enhancements. A User ID 
and Password will also be required with each input request a user makes to an UPS Server while using an 
XML Tool. It is important to note that every time a developer changes their password on the web site they will 
have to update any program that has the Tools embedded. It is recommended that users do not use an 
existing My UPS. Com ID. UPS recommends you keep your MyUPS.Com ID separate from your Tools User 
ID. 

For the Premium XML Tools (e.g., Shipping and Signature Tracking) additional data has to be associated 
with your User ID being passed with each transaction. For Shipping, you must have a valid Shipper 
Numbers) associated with the Registration ID. For Signature Tracking you must have a PDM(s) associated 
with your Registration ID. The special requirements are detailed in the Shipping and Signature Tracking 
Documentation. To be approved for the Premium Tools a registered user submits a request form on the " Get 
Tools" portion of http://www.ec.ups.com . If approved users will be granted access to the premium Tool 
documentation through the web site. 
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For participants in the UPS Online Tools Third Parry Developer Program or other advanced users that have 
a large number of Registration ID's to set up, UPS can provide an XML interface to the Registration system. 

2. License the Tools and receive your Developer Key. 

For a U.S. End-user, you must login to http://www.ec.ups.com with the User ID and Password. A license 
agreement must be accepted on the " Get Tools" portion of http://www.ec.ups.com before gaining access to 
the Tools documentation. After accepting the appropriate Tools licensing agreement, a Developer Key will be 
e-mailed to the registered user. You need to permanently save a copy of your Developer Key for future 
reference. A valid Developer Key is needed to obtain an Access Key and will be needed for technical 
support The developer key identifies the company and contact that is building the EC solution. 

3. Get a XML Access Key. 

You must pass an XML Access Key with each input request to the UPS OnLine Tools server. You can obtain 
your XML Access Key on the " Get Access Key" section of http://www.ec.ups.com . A Developer Key is 
required to get an Access Key. Each Access Key identifies each site where the Tool has been deployed. 

Once you review the technical documentation, you must plan your strategy for those Access Keys you need. 
There are separate Access Keys for the HTML and XML Tools. Additionally, UPS recommends each site 
implementation of your EC solution have separate Access Keys. An example would be a company that is 
implementing the Tools into three parts of their organization in three different cities. In this case, it is 
recommended that you obtain three separate Access Keys to uniquely identify each site. 

If you have requested use of the Premium Tools, do not request an Access Key until after you received 
confirmation from UPS that your Premium Tool request has been approved. 

For participants in the UPS OnLine Tools Third Party Developer Program or other advanced End-users that 
have a large number of Access Keys to set up, UPS can provide an XML interface to the Get Access Key 
process. 

4. Build your EC solution. 

Imbed your User ID & password and Access Key into your Tools enabled EC solution. 

5. Test your EC Tool implementation. 

To ensure that your Tool's enabled EC solution works properly we provide sample code, DTD's and example 
XML documents. These can be found in the " How To" files for each Tool. 

For the Premium XML Tools (e.g., Shipping and Signature Tracking), additional interactions and approvals 
with UPS are required before you go into production. Details of what to do and who to contact are contained 
in the documentation of each premium Tool. 

6. Go into production with your Tools enabled for implementation. 
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Your applications communicate via the Internet with the UPS OnLine Tools server that implements all 
functionality. 



Communication 



An e -commerce application invokes UPS OnLine Tools by initiating Hypertext Transfer Protocol (HTTP) 
communication with the server hosting UPS OnLine Tools. HTTP is an application-level protocol for distributed, 
collaborative, and hypermedia information systems. HTTP is also a generic protocol used to communicate from 
user agents and proxies/gateways to other Internet systems, including those supported by SMTP, NNTP, FTP, 
Gopher, and WAIS. HTTP allows a user to readily exchange XML-formatted messages. 

UPS OnLine Tools use secure HTTP (HIT PS) for your protection and for the protection of UPS. The secure 
transmission ensures that the sender and receiver are the only parties able to decode a transmission. Encrypting 
the HTTP protocol through a Secure Socket Layer (SSL) socket performs H i IPS. Third-party sockets are 
available from a number of vendors. 

All interactions with the UPS OnLine Tools server are through the HTTP POST method. The HTTP message 
content is formatted as an XML document 

UPS OnLine Tools supports HTTP 1 .0 and 1 .1 protocol (refer to HTTP specifications at http://www.w3.org/ 
Protocols/rfcl945/rfcl945) . 

XML 

Extensible Markup Language (XML) is an open standard for defining markup languages to represent structured 
information over the web. XML documents are used for business-to-business communication and data 
interchange between dissimilar systems. Network transfer occurs with standard HTTP over TCP/IP. 

UPS OnLine Tools uses XML documents to communicate with your applications. XML, like its cousin HTML, is 
a subset of Standard Generalized Markup Language (SGML). Whereas HTML is used to tag words, pictures, and 
other media so that they can be rendered the same way by different browsers, XML is used to tag documents and 
data so that different software consumers can interpret mem without ambiguity. 

For example, consider the following text: 

1Z0597X90219590035 

This string can be interpreted in many ways — an invoice number, a purchase order number, or random 
sequence of characters (noise). Using XML to tag the string removes the ambiguity: 

<TrackingNumber>lZ0597X90219590035</TrackingNumber> 

The tagging mechanism of XML guarantees that if documents are structured properly, the data can always be 
parsed. 

UPS OnLine Tools supports XML 1 .0 specification (http://www.w3 .org/TR/1 998/REC-xml-l 99802 1 0 .html) 
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XML Package Carrier Interface 

XML Package Carrier Interface (XPCI) defines a vocabulary and structure for describing packages, shipments, 
and the activity details for package carriers and their customers. XPCI is a set of DTDs that defines the 
terrninology, transaction enveloping, and XML message definitions. For a client to be XPCI-compliant, the client 
must generate a well-formed XML message that validates against the XPCI DTDs. 

Several DTDs, organized into three categories, define XPCI: 

Vocabulary — This DTD defines the basic business vocabulary of XPCI. All tags used in a message are 
defined in this DTD. 

• Interchange — This DTD defines the transaction-enveloping scheme. Every message includes 
transaction information. 

Message — Each message has an associated DTD that defines the vocabulary of the message. 

DTDs 

A Document Type Definition (DTD) is a set of rules that specifies how to use XML markup. It contains specs for 
each element, including what the element's attributes are, what values the attributes can take on, and what 
elements can be contained in others. Trading partners uses DTDs as interface contracts (for example, input/ 
output specifications that programmers use to craft software). DTDs are also used by software to validate the 
syntax of XML documents. DTDs are available on the http://www.ee. ups.com website. 
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To integrate UPS OnLine Tools into your e-commerce applications, you must develop custom code that adapts 
your application s business logic and data to UPS OnLine Tools. You can use any programming language that 
supports HTTP communication across Internet socket and secure connections, such as Java, Visual Basic, or 
C+ + . 

1 . You will need to know how to program URL or socket connections. There are several ways you can 
do this. Which method you choose will depend on your application platform and programming 
language. For example, if you program in Java on any platform, you could use the URLConnection 
Qass, which is part of the Java Development Kit. Alternatively, Microsoft supplies several 
components for use with Visual Basic and ASP (VBScript). 

2. You will need to obtain, or write, a secure socket implementation that supports the SSL standard for 
secure communications. UPS OnLine Tools requires secure HTTP (HTIPS). This data security is 
required for the protection of both the client application and UPS; sensitive (billing-related) data is 
being transferred back and forth across the public Internet. 

3. You will need to know how to encode and decode XML documents. To program XML documents, 
you'll probably want to use an XML parser, which provides an Application Programming Interface 
(API) for manipulating XML documents. There are several XML parsers available as freeware, as 
well as commercial software products. (See Bibliography for more information.) 

4. You will need to design a strategy into your software for handling errors. Consider that there are 
three types of errors: hard errors, transient errors, and warnings. For a smoothly running application 
you must decide how you handle each type of error. In some cases it may be appropriate to display 
the error to the user. On the other hand, if there is no GUI in your application, your software must 
decided what to do. For instance, if you are designing a GUI interface, you must decide whether to 
show transient errors or simply retry the request behind the scenes. In all cases, we will supply an 
error number and a natural language error message. 

5. You will need to establish a connection to the Internet from the computer that runs your e-commerce 
application. You also need to establish Internet access with your own Internet Service Provider. 



Planning the OnLine Tools Integration 

A successful implementation of the UPS OnLine Tools depends on many factors. It is important that you have the 
appropriate tools to work with the platform you are integrating with, the appropriate skill set (XML knowledge 
and/or experience) as well as a project plan and design. The following checklist should aid in the process: 

1 . Obtain user ID, password and developer s key from http:/ec.ups.com/ecommerce . (See " Security 
Elements" in the Product Overview section.) 

2. Obtain documentation and the corresponding " How To" file for the tool you wish to 
implement. 

3. Carefully review the documentation. 
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4. 



6. 
7. 
8. 
9. 
10. 

11. 



Obtain parser and utility software for SSL. For tools returning graphic images (Signature 
Tracking and Shipping), obtain software forBase64 Encoding. 

Determine how your application will connect to the Internet. This may involve discussions 
with your network administrator and/or network security staff. 

Develop a plan for error handling. 

Develop your application. 

Obtain Access Key. (See " Security Elements" in the Product Overview section.) 
Perform integration testing with the UPS OnLine Tools server. 

For Signature Tracking and Shipping, follow the product certification process identified in 
the Customer Integration Environment section. 
Launch your application. 



Communication 



An application invokes UPS OnLine Tools by initiating HTTP communication with the server hosting 
UPS OnLine Tools. All interactions with the host server are through the HTTP POST method. The 
HTTP message content sent is formatted as an XML document. 

Applications connected to the Internet can connect directly to UPS OnLine Tools at the HTIPS port 
443 , by opening either a secure TCP/IP socket or secure URL connection. Applications send request 
data to UPS OnLine Tools by writing data to the TCP/IP socket or URL connection. The request data 
must be formatted as a valid XML request message and adhere to the HTTP protocol. Applications 
receive the response data from UPS OnLine Tools by reading data from the same TCP/IP socket or URL 
connection. 

HTTPS is accomplished by using the HTTP protocol using a secure (SSL) socket. You must obtain an 
SSL package that supports the RSA encryption algorithm in order to communicate with the UPS OnLine 
Tools server. 



Invoking UPS OnLine Tools via XML 



An application creates an XML document containing the content required by the interface to be 
invoked. The application also provides the access tokens needed for the interface to be invoked. The 
application must know which URL to use to access the desired interface. 

Upon establishing connection with the URL, the application sends the HTTP message to the URL using 
the POST method. The request HTTP message consists of a header section and a content section. The 
header section specifies the HTTP method (POST), the content type (application/xml), the content 
length, and so on, as per HTTP 1 .0 or 1 .1 specification. The content of the HTTP message is the XML 
document containing the data needed for the interface to be invoked. The application waits for a 
response. 

The interface receives the HTTP content, and attempts to parse the received XML document and 
perform the requested action. 
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The interface generates new XML content to be returned to the application. The content type is set to 
application/xml. The response is returned to the HTTP server, which sends it to the application. 

The application, upon receiving die response, extracts the content according to the content type, and 
evaluates die response to determine if the desired service was rendered. 

Base64 Encoding 

Note: Base 6 4 Encoding is only requin?d /or Signature Tracking and Snipping. 

Base 6 4 encoding is used to preserve binary data. The UPS Online Tools server uses Base 6 4 encoding to 
preserve images. Listed below are links to help you better understand Base64 encoding. 

• This details Sun's interface in one of its packages that codes and decodes Base64 
http://java.sun.com/ products/ commerce/ release, 1 Oeal / api/Package-javax.commerce .utiLhtml 

• This link contains a detailed discussion of the RFC and its implications 
http://www.freesoftorg/CIE/RFai 521/7 .htm 

• These sites offer classes, which code and decode Base64 . We have not tested, much less 
investigated these, and suggest you do your own search and due diligence investigations. 

http://vvww.fourmilab.ch/vvebtools/base64/ 

http://www.davecentral.com/7202 .html 



Secure Socket Layer (SSL) 

SSL technology is used to protect sensitive data while traveling over public domains. UPS requires you 
to use SSL for all transactions. The following sites contain more information on SSL. They are listed 
for your convenience. UPS does not endorse these sites or products in any way. 

These Sun sites contain a good guide to SSL issues, one for JDK 1 . 1 , the other for JDK 1 .2 : 

http:// java.sun.com/ products/ jdk/1 .2/docs/ guide/ rmi/ SSLInfo . html 

http://iava.sun.com/security/ssl^ 

http://www.phaos .com/ solutions.html 

• This site is the home for a free SSL implementation written in Java. These are listed for your 
convenience. 

http://speedy.itfm.com/puretis/ 

• These sites offer licensed SSL implementations for Java. 
http://www.certicom .com/ products/ sslplus_java.html 
http://www.alphaworks.ibm.com 

UPS OnLine Tools support the following browsers: 

• Netscape Navigator 3.0 and later 

• Microsoft Internet Explorer 3 .02 and later 

• America Online 3 .0 and later 
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XPCI 



XML Package Carrier Interface (XPCI) defines a vocabulary and structure for describing packages, 
shipments, and the activity details for package carriers and their customers. XPCI is a set of DTDs that 
defines the terminology, transaction enveloping, and XML message definitions. For a client to be XPCI- 
compliant, the client must generate a well-formed XML message that validates against the XPCI DTDs. 

UPS OnLine Tools demand as a pre-condition that all messages be XPCI-compliant. This means mat 
each message must validate against its corresponding DTD, however, the XML message itself should not 
contain a DOCTYPE. UPS OnLine Tools do not use the XML DOCTYPE reference. 



Connecting and Messaging 



To invoke UPS OnLine Tools: 

1 . Open a secure TCP/IP socket or secure URL connection using the connection address for the 
interface to be invoked. 

2. Create an XML request message. All messages must be XPCI-compliant. 

3. Send the XML request message to the tool. To send a request message to a tool, an 
application writes a stream of data to the tool via a secure TCP/IP socket or secure URL 
connection. The data stream must be in the form of an HTTP POST request message. 

4. Receive the XML response message from the tool. To read a response from a tool, an 
application reads the response in XML format via a secure TCP/IP socket or secure URL 
connection. 

5. Parse the XML response message to retrieve data. 

6. Identify and handle error conditions. 



Transaction Framework 



The XPCI defines a common element found on all transactions. This container node, labeled 
TransactionReference, contains the transaction specific information CustomerContext and XPCI 
Version. 

XpciVersion controls a transaction language's version separately from the vocabulary of business terms. 
XpciVersion identifies the version of the transaction language. The implied version is the most recent 
version. The tag XpciVersion identifies the version of the business vocabulary. 

Hie client uses CustomerContext to synchronize request/response pairs. The client establishes 
CustomerContext, which can contain any information you want, as long as it is valid XML; it is echoed 
back to the server. 

The success or failure of a transaction is detailed in ResponseStatusCode and 
ResponseStatusDescription. The UPS XPCI server only supports synchronous interchanges at this 
time. XPCI compliant transactions always contain a request and a response. 
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Interchange Interface Specification 



Each UPS OnLine Tools interchange contains common elements. These elements are used to frame each 
request, response, and error. 

The UPS OnLine Tools interchange operates within an HTTP 1 .0 framework. An XML request is sent 
to an interface via the HTTP POST method. An XML response is returned. The interchange is 
synchronous (that is, the UPS OnLine Tools client thread waits for the UPS OnLine Tools server to 
respond). 

The following XPCI tables represent the interchange interface elements involved in the UPS OnLine 
Tools transactions. 



Table 1: XPCI Interchange INPUT Element Definitions 

Element (Xpath) Required Type Length Description/Values 



Request/ 

TransactionReference/ 
CustomerContext 


No 


ANY 


0..512 


Customer provided data. 
May be XML. This data is 
echoed back to the 
customer. 


Request/ 

TransactionReference/ 
XpciVersion 


No 


Alphanumeric 


1..50 


Identifies the version of the 
message. Currently the only 
supported version is 1 .0001 


Request/RequestAction 


Yes 


Alphanumeic 


1..15 


Identifies the function to be 
invoked. 

Each Tool has a unique ED 
name. 


Request/RequestOption 


No 


Alphanumeic 


1..15 


Identifies the optional 
processing to be performed. 
Each service defines the 
possible options. 
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On a successful exchange with the Tools, only the first four elements below will be returned as output If 
an error occurs, additional fields will be populated. 

Table 2: XPCI Interchange OUTPUT Element Definitions 

Element (Xpath) Required Type Length Description / Values 



Response/ 

i rEuisacuoniveierence/ 
CustomerContext 


No 


Any 


0..512 


Customer provided data. 

If this data is present in the 
request, it is echoed back to 
the customer. 


Response/ 

TransactionRefe rence/ 
XpciVersion 


No 


Alphanumeric 


1..50 


Identifies the version of the 
message. Currently the only 
supported version is 
1.0001. 


Response/ 

ResponseStatusCode 


Yes 


Numeric 


1 


Identifies the success or 
failure of the interchange. 
1 = Successful interchange 
0 = Failed interchange 


Response/ 

ResponseStatusDescription 


No 


Alphanumeric 


1..15 


Describes the Response 
Status Code. 


Response/Error 


No 


Container 


N/A 


If an error is encountered 
during the interchange, the 
Response contains an error. 
If the error is present, then 
the ErrorSeverity and 
ErrorCode are required. 


Response/Error/ 
ErrorSeverity 


Yes 


Alphanumeric 


1..15 


Describes the severity of the 
error. 

TransientError- Customer s 
data has not been processed 
due to system unavailability. 
The customer has to wait 
and try again. 
HardError - The error was 
encountered processing the 
customer s data and that the 
data needs correction. 
Warning - The customer s 
data was successfully 
processed; however, there 
were warnings encountered 
during processing. 
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Table 2: XPCI Interchange OUTPUT Element Definitions 



ReS|X>nse/Errt)iyErrorCode 


Yes 


Numeric 


1..15 


A numeric value that 
describes the error. 
Each tool defines a range of 
error codes. Refer to Error 
Conditions, in the 
appropriate chapter, for a 
complete list of interchange 
errors. 


Response/Error/ 
ErrorDescription 


No 


Alphanumeric 


1.-50 


Describes the error code. 


Response/Error/ 
MinimumRe try Seconds 


No 


Numeric 


1..5 


Number of seconds to wait 
until retry. This field is 
populated on special 
conditions of the Transient 
Error only, as defined by 
the service. 

A number between 1 and 
86400 (24 hours) 


Response/Error/ 
ErrorLocation 


No 


Container 


N/A 


Identifies the element in 
error. 


Response/EmW 
ErrorLocation/ 
EmorLocationElement 
Name 


No 


Alphanumeric 


1..512 


The XPATH name of the 
element in error. This is a 
valid XPATH pointing to an 
element in the request 
document. 


Response/Error/ 
ErrorLocation/ 
ErrorLocatioiiAttribute 
Name 


No 


Alphanumeric 


1..50 


The name of the attribute in 
error. This is the name of 
the attribute contained by 
the Error Location Element. 


Response/Error/ 
ErrorLocation/Ent)rDigest 


No 


Alphanumeric 


Bound by 
the size of 
the 

Request 
data. 


The contents of the element 
in error. 
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Data Type Codes 



UPS OnLine Tools supports the XML 1 .0 specification, as recommended by the World Wide Web 
consortium (http:/ / wwvvw3 org/TR/REG-xml) . All message data must conform to this specification. 

All message data is text (a sequence of characters), which may represent markup or character data. A 
character is an atomic unit of text, as specified by ISO/DSC 10646 . Legal characters are tab, carriage return, 
line feed, and the legal graphic characters of Unicode and ISO/IEC 10646. The use of compatibility characters, 
as defined in The Unicode Standard, Version 2 .02* , is discouraged. 

Supported Character Set 

UPS OnLine Tools supports the UTF-8 and ISO-8859-1 character sets. 
Dates, Times, and Numbers 

Reducing all data to character data simplifies many aspects of message parsing and transport. 
However, this also creates problems when more complex data is needed. Since all data is text, dates, 
times, and numbers require agreement, with regard to their representation. UPS OnLine Tools use 
the following representation of dates, times and numbers. 

Table 3: Representation of Dates, Times, and Numbers 



Data Type 


Description 


Date 


Two date formats are supported: 
YYYY-MM-DD and YYYYMMDD 


Time 


Two time formats are supported: 

HHMMSS and HH:MM:SS, where HH is the hour field and uses a 2 4 -hour 
clock (military time). All time is based on LOCAL time zone. 


Number 


Decimal numbers are represented with 2 decimal positions. Integers are 
represented without any decimal points. 


Telephone Number 


Only digits 0-9 are allowed. Length must be between 10 and 14 digits. 



* ISO (International Organization for Standardization). ISO/IEC 1 0646- 1 993 (E). Information technology ~ Universal Multiple-Octet Coded 
Character Set (UCS) — Part 1: Architecture and Basic Multilingual Plane. [Geneva]: International Organization for Standardization, 1993 (plus 
amendments AM 1 through AM 7). 

t The Unicode Consortium. The Unicode Standard, Version 2.0. Reading, Mass.: Addison- Wesley Developers Press, 1 996. 
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The following text and examples illustrate HTTP requests and responses. The examples illustrate the 
HTTP POST command and all necessary headers. The response shows the response headers and 
response data. The bold LF in the XML is added for formatting and does not exist in the actual data. 

XML Request Messages over HTTP 
Every HTTP request consists of four parts: 

request line 

• header fields 

• empty line 

• message body 

Sending Requests 

To send a request to a tool, an application writes a stream of data to the tool via a TCP/IP socket 
or URL connection. The data stream must be in the form of an HTTP request message. An 
application can create a formatted request message in a buffer, and then write the contents of the 
buffer to the tool. The exact syntax used to write the buffer to the tool varies, depending on the 
programming language and the communication API is being used. 

Request Line 

The request line comprises the following three elements: 
Method 
Request-URL 

• HTTP-version, and ending with carriage-return-line-feed (CRLF) string 
Table 4: Request Line Elements 

Element Description 

Indicates the method for sending data to the resource identified by the Request- 
URL. Method is case-sensitive. 

Though other values are possible, the UPS OnLine Tools require this be set to 
POST. 

Request-URL The location of the tool to which the message data should be sent. 

HTTP-version The HTTP version of the message. 

Header Fields 

Header fields provide general information about a request. To understand what kind of data is 
being received, every request containing a message body should include a Content-type header. 
The Content-type header field indicates the media type (text, html, image, etc.) of the message 
body sent to the recipient. For the POST method, HTTP requires that the Content-Length 
header be supplied. The Content-Length provided in the header is the length, in bytes, of the 
message body. 
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Empty Line 

After the necessary headers are added to the request, an empty line must be added to indicate 
the end of the header fields and the start of the message body, if there is one. 

Message Body 

The message body contains the information to be processed by a tool. The message must be 
XPCI-compliant. 

HTTP Request Example 

Request: POST / toolname/l . 0 
Content -Type : application/xml 
Content -Length: 273 

<?xml version="l . 0" encoding="UTF-8"?>LF . . . 

Within the request line, each element is separated by a blank space (SP). No CRs or LFs are 
allowed, except in the final CRLF sequence. The structure of the request line is shown below, 
followed by an example. 

Request Line = Method SP Request -URL SP HTTP- version CRLF 

Example: POST /register HTTP/1.0 

XML Response Messages over HTTP 

Every response consists of four parts: status line, header fields, empty line, and message body. 
Reading Responses 

To read a response from a tool, an application reads the response in XML format via a TCP/IP 
socket or URL connection. The application parses the data out of the response data stream. The 
# exact syntax of the response complies with the XPCI specification. 

Status Line 

The status line comprises three elements: 
HTTP-version 
Status-Code 

Reason-Phrase, and ending with carriage return-line feed (CRLF) string 
Table 5: Status Line Elements 



Element 


Description 


HTTP-version 


The HTTP version of the message. 


Status-Code 


A 3 -digit integer result code of the attempt to understand and satisfy the request 


Reason-Phrase 


A short textual description of Status-Code. 
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HTTP Response Example 



HTTP/1.1 200 OK 

Server: Netscape-Enterprise/3 . 6 
Date: Fri, 06 Aug 1999 LF 
21:04:44 GMT 

Content -type: application/xml 

<?xml version= H l .0" encoding="UTF-8" ?>LF 

Within the status line, each element is separated by blank spaces (SP). No CRs or LFs are allowed, 
except in the final CRLF sequence. The structure of the status line is shown below, followed by an 
example. 

Status Line = HTTP-version SP Status -Code SP Reason- Phrase CRLF 
Example: HTTP/1.0 200 OK 
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UPS Returns on the Web 



Introduction 

Improve your online customer service with UPS Returns On The Web, available in the latest XML 
technology. This powerful UPS OnLine Tool provides your customers with the option to return a product 
using the same technology to which they submitted the purchase. 

You can know track a return package while making your customers return experience more pleasant. 
With UPS Returns On The Web, You Can: 

• Provide your customers with return options. 

• Improve customer service by giving your inventory management system consistent, up-to-date shipping 
information. 

Your Customers Can: 

• Receive return delivery options when returning a package. 
Receive a prepaid return label. 

• Arrange for a package pickup time. 

For more information on UPS OnLine Tools, including UPS Returns On The Web, please visit 
http://www.ec.ups.com . 

Tool Overview 

The " Returns on the Web" service offering is initiated by a Merchant request for an UPS Return Service. 
After the request is received and processed, the response includes shipping data and an electronic label to 
the Merchant. The Merchant can then integrate carrier data with order information and pass the label to 
their customer via e-mail, or the customer s browser. The value provided is a result of the integration of a 
Merchants technology with UPS technology. Each solution will be slightly different according to each 
Merchant's returns business rules. 

Returns on the Web service originates from the End Consumer requesting return service using the phone or 
the Merchant's Web site. The return request will generate a label to facilitate returning the packages to the 
correct vendor. In the event the Consumer or Merchant does not receive the label or misplaces the shipment 
label, the Returns on the Web Label Recovery tool contains the ability to recover the label up to 30 days 
from the request using either the Tracking Number or the Reference Number and Shipper Number. Labels 
can be generated in real-time and be instantly ready for printing from browser or be sent via e-mail. 

This release of the tool will not support Hazardous Materials and World Wide Returns. The March release of 
Returns On The Web only facilitates returns for US 50. 



Connection Addresses 
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Key Concepts 

Merchant - Often referred to as Web Merchant or Shipper. However, it should be noted the use of this 
application is not limited to Web Merchants, any customer can integrate Returns On The Web. The 
Merchant is a UPS customer who wishes to facilitate returns using the Internet. 

End Consumer - Also referred to as customer. The End consumer is the Merchant's customer who initiates 
the request for a return. 

Vendor - Often referred to as the destination. The Vendor is the entity who receives the returned goods. 
Use Cases 

The following use cases describe possible business applications for the UPS Online Returns on the Web 
Tool. Contact with UPS with any further questions you may have regarding your intended application for the 
tool. 

< INSERT USE CASES> 
Returns on the Web Processes 



The process for Returns on the Web is designed to support a Web Merchant who has a need to reciprocate a web 
sale transaction with a web return transaction. This process facilitates the return by enabling the presentation of a 
return label in electronic format at Internet speed. The usual delay associated with getting a " pre-paid" shipping 
label into the end consumer 1 s hands is overcome by the ability to present, and therefore print, that label from the 
end consumer 1 s browser, the very same vehicle from which the original transaction was likely conceived. The 
service enables Merchants to provide their customers with the Print Return Label (PRL) , Return Notification and 
Pickup Notification online return shipping options. 

The Return Notification is a e-mail notification of a return at the package level. The return notification allows the 
user to supply the relevant End Consumer, Vendor and Shipper information, where Shipper is required in the 
event of e-mail failure. Whatever e-mail addresses are present the tool can provide the recipient with return 
notification e-mail. This notification allows the End Consumer, the Merchant, and the Vendor, to track the 
package as it is returning to mem. The e-mail will consist of the manufacturing companies address information, 
the customer s address information, UPS contact information, a Tracking Number, a tracking URL with and 
without a Tracking Number, a Shipment Reference Number (RMA), the Service Level and the Shipment Weight. 

The Pickup Notification option is available at die shipment level. Pickup Notification will not allow a label image 
or URL to be passed in the XML document Pickup Notification will send confirmation e-mail to the originator s 
e-mail address, i.e. the End Consumer s e-mail address. The confirmation e-mail will indicate the status of the 1 
Attempt or 3 Attempt request, expected first attempt pickup {Next Business Day), Tracking Number and the 
Tracking URL with the Tracking Number. An UPS compliant shipping label is then issued to Merchant for 
distribution to the End Consumer. The End Consumer will package, label, and submit parcels to UPS. 
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The basic process for all e-mail notification is as follows: 



Consumer 



Merchant 



UPS 



Vendor 



1) Requests Returns 



5) Label Returned 
by Merchant 



2)XML Return Request 



4) Label Returned 
via XML Response 



3)Return Notification 



Figure 1: Print the Return Label by sending the XML To the Merchant 



Consumer 



Merchant 



UPS 



Vendor 



1) Requests Returns 



2)XML Return Request 



3) XML Confirmation 



5)E-Mail the Label 



4)Optional 
Return Notification 



Figure 2: Print the Return Label by sending the Label to the Consumer via E-mail 



Consumer 



Merchant 



UPS 



UPS Center 



Vendor 



1) Requests Returns 



2)XML Return Request 



4) XML Confirmation 



6)Optional Pickup Noufication E-Mail 



3) Print 1A/3A 
Label 



1 

5)Optional Return Notification 



7) Driver Picks up Shipment 



Figure 3: Pickup Notification 
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For documentation purposes the elements that do not require population are not provided in this document. 

Return Request DTD 

When Returns On The Web information is needed for a particular shipment, a Return Request must be 
created and sent to the UPS Online Tools server for processing. The request must include several pieces of 
information and may include additional shipment information, depending upon the type of package being 
returned. For a Return of a document, the request must include: 

• Request Action 

• Ship From Information 

• Ship To Information 

• Shipper Information 

• Delivery Service Type 

• Payment Information 

• Package Type 

• Return Service Type 

• Merchandise Description 

These data elements must be sent to the UPS OnLine Tools server in the required XML format for Returns 
On The Web services to be rendered. 

Return Response DTD 

Based upon the user supplied inputs into the Return Request document the user will receive a document with 
a summary of the supplied information as well as, a breakdown of the return charges, billing weight, a 
Shipment Identification Number, a Package Tracking Number, and a label. 

Returns on the Web Guidelines 

Table Notes 

The following input and output tables are for reference only and may include data elements that are 
contained in the DTD, but are not relevant to the use of this Tool. Those elements that are required or are 
optional for this tool are not shaded. Those elements that are " Not Relevant For This Tool" or are " Not 
Populated for This Release" are shaded in gray. 



Description/Value Definitions 

• Can Be Used — the data element is optional and can be used in accordance with the terms specified in 
the Validation Rules. 

• Defaults To — identifies the default values for data elements that are not populated. 

• Format — identifies specific formats that will be recognized for a specific data element Usually used for 
data elements which identify Times (HHMM) or Dates (YYYYMMDD). 

• Not Populated for This Release — the referenced data element is not used for this release of this Tool, 
but may be used in a future release. The data element will not be processed, however, no error will be 
returned. 

• Not Relevant for This Tool — the referenced data element is not pertinent to this tool. However, if 
passed, the data element will not be processed and an error message will not be returned. 
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• Required For — the referenced data element will be processed if the conditions identified are met. If 
the conditions are not met, the element may be ignored or an error returned (if stated rules are 
violated). 

Valid Values — identifies the specific values or parameters that will be recognized for die referenced 
data element. 

Return Request Input 

DTD Definition 

< 1ELEMENT ReturnRequest (Request, LabelSpecification? , Shipment)> 
Table 1: Return Request Input 

Required/ 



Element (Xpath) 


Cardinality 


Type 


Length 


Description/Values 


KeturnKequest/ Request 


Yes/ 
One 




Container 




RetumRequest/Request/ 
RequestAction 


Yes/ 
One 


#PCDATA 


13 


Indicates the action to be taken by 
the XML service. 
Must be ' Return 1 . 


RetumRequest/Request/ 
TransactionReference 


No/ 

Zero or One 




Container 


TransactionReference identifies 
transactions between client and 
server. 


RetumRequest/Request/ 

TransactionReference/ 

CustomerContext 


No/ 

Zero or One 


#ANY 


1..512 


Hie client uses CustomerContext 
to synchronize request/response 
pairs. The client establishes 
CustomerContext, which can 
contain any information you want, 
as along as it is valid XML; it is 
echoed back by the server. 


RetumRequest/Request/ 

TransactionReference/ 

XpciVersion 


No/ 

Zero or One 


#PCDATA 


4 


Message version. Defaults to 
'1.0002*. 


RetumRequest/Request/ 
Testlndicator 


No/ 

Zero or One 


EMPTY 


0 


If the indicator is present then the 
document is a test return 
shipment. Meaning, nothing the 
user inputs will be recorded for 
Returns. 
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Table 1: Return Request Input 



RetumRequest/ 
LabelSpecification 


No/ 

Zero or One 




Container 


Container used to define the 
properties required by the user to 
print and/or display the label. 
Should the user choose not to 
populate the fields, the 
LabelPrintMe thod/ Code will 
default to gif, HTIPUserAgent will 
default to Mozilla/4 .5 and 
Labellmagerorrnat/Lode will 
default to gif. 


RetumRequest/ 

LabelSpecification/ 

I^belPrintMethod 


Yes/ 
One 




Container 


The device used to print a label 
image. 


RetumRequest/ 

LabelSpecification/ 

LabelPrintMethod/Code 


Yes/ 
One 


#PCDATA 


3 


Label print method code that the 
labels are to be generated for 
EPL2 formatted labels use 'EPL' 
and for image formats use 'GIF*. 
Valid values are 'GIF' and *EPL\ 


RetumRequest/ 

LabelSpecification/ 

HTIPUserAgent 


Cond/ 

Zero or One 


#PCDATA 


1..64 


Browser HTIPUserAgent String. 
This is the preferred way of 
identifying GIF image type to be 
generated 

Required if RetumRequest/ 
LabelSpecification/ 
LabelPrintMethod/Code = GIF. 


RetumRequest/ 

LabelSpecification/ 

i^aoeioiocKOize 


Cond 




Container 


The size of the label stock used to 
render a label image. See also 
ijmu_/iivieasurement, neigriL, 
Width. 


RetumRequest/ 

LabelSpecification/ 

LabelStockSize/Height 


Cond/ 
One 


#PCDATA 


1..3 


Width of the label image. For IN, 
use whole inches. 
ForEPL2 labels only. Valid values 
are '6' or '8*. 


RetumRequest/ 

LabelSpecification/ 

LabelStockSize/Width 


Cond/ 
One 


#PCDATA 


1..3 


Height of the label image. For IN, 
use whole inches. 
For EPL2 labels only. Only valid 
value is *4\ 


RetumRequest/Shipment/ 
Shipper 


Yes/ 
One 




Container 


Shipper of record for a shipment. 


RetumRequest/Shipment/ 
Shipper/Name 


Yes/ 

Zero or One 


#PCDATA 


1..35 


Shippers company name. 


RetumRequest/Shipment/ 
Shipper/ AttentionName 


No/ 

Zero or One 


#PCDATA 


1..35 


Shippers Attention Name 
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Table 1: Return Request Input 



RetumRequest/Shipment/ 
Shipper/ 

Taxlde ntificationNumber 


No/ 

Zero or One 


#PCDATA 


1..15 


Shippers Tax Identification 
Number 


RetumRequest/Shipment/ 
Shipper/PhoneNumber 


Cond/ 
Zero or One 


Mixed: 

#PCDATA 

or 

Structured 
Phone 
Number 
element 


1..10 


Shipper's Phone Number 

10 digits allowed. 

Refer to the Universal Rules table 

in Appendix C. 


RetumRequest/Shipment/ 
Shipper/PhoneNumber/ 
StructuredPhone Number 


Cond/ 
Zero or One 




Container 


Required if parent element, 
Phone Numbe r. 


ReturnRequest/Shipment/ 
Shipper/PhoneNumber/ 
StructuredPhone Number/ 
Phone DialRanNumber 


Yes/ 
One 


#PCDATA 


1.-10 


Dial plan number portion of the 
phone number. 

Refer to the Universal Rules table 
in Appendix C. 


RetiimRequest/Shipment/ 
Shipper/PhoneNumber/ 
StmcturedPhoneNumber/ 
PhoneLineNumber 


Yes/ 
One 


#PCDATA 


1..10 


Line number portion of the phone 
number. 

Refer to the Universal Rules table 
in Appendix C. 


KetumKequest/onipment/ 
Shipper/PhoneNumber/ 
StmcturedPhoneNumbery 
Phone Extension 


JNo/ 

Zero or One 




1 A 
I ..ft 


Shipper s phone extension. 


RetumRequest/Shipment/ 
Shipper/ShipperNumber 


Yes/ 
One 


#PCDATA 


6 


Shipper s six digit alphanumeric 
account number. 
Must be associated with the 
Internet account used to login. 


RetumRequest/Shipment/ 
Shipper/Address 


Yes/ 
One 




Container 


Information that specifies a 
physical location. 


RetumRequest/Shipment/ 
Shipper/ Address/ 
AddressLine 1 


Yes/ 
One 


#PCDATA 


1.35 


Address Line 1 of the shipper. 


RetumRequest/Shipme nt/ 
Shipper/ Address/ 
AddressLine2 


No/ 

Zero or One 


#PCDATA 


1..35 


Address Line 2 of the shipper. 
Usually Room/Floor information. 


RetumRequest/Shipment/ 
Shipper/Address/AddressLine3 


No/ 

Zero or One 


#PCDATA 


1 .35 


Address Line 3 of the shipper. 
Usually department information. 


RetumRequest/Shipme nt/ 
Shipper/ Address/ City 


Yes/ 
One 


#PCDATA 


1..30 


Shippers city. 



o 
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Table 1: Return Request Input 



RetumRequest/Shipment/ 
Shipper/ Address/ 
StatePro vince Code 


Yes/ 
One 


#PCDATA 


2 


Shipper's state code. 
Must be a valid US State 


ReturnRequest/Shipment/ 
Shipper/Address/PostalG)de 


Yes/ 
One 


#PCDATA 


5,9 


Shipper's postal code. 
5 or 9 digits are required. 


RetumRequest/Shipme nt/ 
Shipper/ Address/ CountryCode 


Yes/ 
One 


#PCDATA 


2 


Shipper's country code. 
Valid value must be: 'US' 


ReturnRequest/Shipment/ 
ShipTo 


Yes/ 
One 




Container 


Address and contact information 
describing the location where a 
return is to be delivered. 


ReturnRequest/Shipme nt/ 
bhip 1 ol (JompanyName 


Yes/ 
Une 


#PCDATA 


1..35 


Consignee's company name. 


ReturnRequest/Shipment/ 
ShipTo/ AttentionName 


Yes/ 
One 


# PCDATA 


1..35 


Contact name at the consignee's 
location. 


ReturnRequest/Shipment/ 
ShipTo/PhoneNumber 


No/ 

Zero or One 


Mixed: 

#PCDATA 

or 

Structured 
Phone 
Number 
element 


1..10 


Consignee's phone number. 
10 digits are allowed 
Refer to the Universal Rules table 
in Appendix C. 


RetumRequest/Shipment/ 
ShipTo/PhoneNumber/ 
Structure dPhone Number 


Cond/ 
Zero bo One 




Container 


Required if parent element, 
Phone Number, is required and a 

nhnnp I■^llml"w*^ , not rwrwiHp ?it the 

parent node. 


ReturnRequest/Shipment/ 

ShipTo/PhoneNumber/ 
Stnir ti irpd PhnnpNumhp rr 
PhoneDialRanNumber 


Yes/ 
One 


#PCDATA 


1..10 


Dial plan number portion of the 
phone number. 

Refer to the Universal Rules table 

A xJt- lv A Ul KM m.%-* wlU Jul i\uiWv> kmm,k**.k* 

in Appendix C. 


RetumRequest/ Shipment/ 
ShipTo/PhoneNumber/ 
StructuredPhoneNumber/ 
PhoneLineNumber 


Yes/ 
One 


#PCDATA 


1..10 


Line number portion of the phone 
number. 

Refer to the Universal Rules table 
in Appendix C. 


ReturnRequest/Shipment/ 
ShipTo/PhoneNumber/ 
StructuredPhoneNumber/ 
Phone Extension 


No/ 

Zero or One 


#PCDATA 


1.4 


ShipTo's Phone extension. 


ReturnRequest/Shipment/ 
ShipTo/Address 


Yes/ 
One 




Container 


Information that specifies a 
physical location. 


ReturnRequest/Shipment/ 
ShipTo/Address/ AddressLine 1 


Yes/ 
One 


#PCDATA 


1..35 


Address Line 1 of the consignee. 
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Table 1: Return Request Input 



RetumRequest/Shipme nt/ 
ShipTo/ Address/ AddressLine2 


No/ 

Zero or One 


#PCDATA 


1..35 


Address Line 2 of the consignee. 
Usually Room/Floor information. 


RetumRequest/Shipme nt/ 
ShipTo/Address/AddressLine3 


No/ 

Zero or One 


#PCDATA 


1..35 


Address Line 3 of the consignee. 
Usually department information. 


RetumRequest/Shipment/ 
ShipTo/Address/City 


Yes/ 
One 


#PCDATA 


1..30 


Consignee's city. 


RetumRequest/Shipme nt/ 
ShipTo/ Address/ 
StateProvinceCode 


Yes/ 
One 


#PCDATA 


2 


Must be a valid US State 


RetumRequest/Shipment/ 
ShipTo/ Address/PostalCode 


Yes/ 
One 


#PCDATA 


5,9 


Consignee's postal code. 
5 or 9 digits are required. 


RetumRequest/Shipme nt/ 
ShipTo/Address/ CountiyCode 


Yes/ 
One 


#PCDATA 


2 


Consignee's country code. 
Valid value must be: ' US' 


RetumRequest/Shipment/ 
ShipFrom 


Yes/ 
One 




Container 


Address and contact information 
describing the location where a 
shipment is to be picked up. 


RetumRequest/Shipment/ 
ShipFrom/ CompanyName 


Yes/ 

Zero or One 


#PCDATA 


1..35 


Consumer s company name . 


RetumRequest/Shipme nt/ 
ShipFrom/AttentionName 


No/ 

Zero or One 


#PCDATA 


1..35 


Contact name. 


RetumRequest/Shipment/ 
ShipFrom/PhoneNumber 


Cond/ 

Zero or One 


Mixed: 

#PCDATA 

or 

Structured 
Phone 
Number 
element 


1..10 


Consumer s phone number. 
1 0 digits are allowed 
Refer to the Universal Rules table 
in Appendix C. 


RetumRequest/Shipment/ 
ShipFrom/PhoneNumbei/ 
otnjcturedrhone N umber 


Cond/ 
Zero to One 




Container 


Required if parent element, 
Phone Numbe r, is required and a 

nhnnp numhpr not rwnviHf* zit thf* 

parent node. 


RetumRequest/Shipme nt/ 
ShipFrom/PhoneNumber/ 
Structure dPhoneNumbe rl 
PhoneDialRanNumber 


Yes/ 
One 


#PCDATA 


1..10 


Dial plan number portion of the 
phone number. 

Refer to the Universal Rules table 
in Appendix C. 


RetumRequest/Shipment/ 
ShipFrom/PhoneNumber/ 
Structure dPhone Numbe r/ 
PhoneLineNumber 


Yes/ 
One 


#PCDATA 


1..10 


Line number portion of the phone 
number. 

Refer to the Universal Rules table 
in Appendix C. 
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RetumRequest/Shipment/ 
ShipFrom/PhoneNumbei/ 
Structure dPhone Number/ 
Phone Extension 


No/ 

Zero or One 


#PCDATA 


1..4 


ShipFrom's Phone extension. 


RetumRequest/Shipme nt/ 
ShipFrom/ Address 


Yes/ 
One 




Container 


Information that specifies a 
physical location. 


RetumRequest/Shipment/ 

ShipFrom/Address/ 

AddressLinel 


Yes/ 
One 


#PCDATA 


1..35 


Address Line 1 of the pickup 
location. 


RetumRequest/Shipment/ 

ShipFrom/Address/ 

AddressLine2 


No/ 

Zero or One 


#PCDATA 


1..35 


Address Line 2 of the pickup 
location. Usually Room/Floor 
information. 


RetumRequest/Shipment/ 

ShipFrom/Address/ 

AddressLine3 


No/ 

Zero or One 


#PCDATA 


1..35 


Address Line 3 of the pickup 
location. Usually department 
information. 


RetumRequest/Shipment/ 
ShipFrom/ Address/ City 


Yes/ 
One 


#PCDATA 


1..30 


Pickup location's city. 


RetumRequest/Shipme nt/ 
ShipFrom/Address/ 
StatePro vince Code 


Yes/ 
One 


#PCDATA 


2 


Pickup location's state code. 
Must be a valid US State. 


RetumRequest/Shipment/ 

ShipFrom/Address/ 

PostalCode 


Yes/ 
One 


#PCDATA 


5,9 


Pickup location's postal code. 
5 or 9 digits are required. 


RetumRequest/Shipment/ 

ShipFrom/Address/ 

CountryCode 


Yes/ 
One 


#PCDATA 


2 


Pickup location's country code. 
Valid value must be: 'US' 


RetumRequest/Shipment/ 
Paymentlnformation 


Yes/ 
One 




Container 


Requires either UPS Account 
number. 


RetumRequest/Shipment/ 
Paymentlnformation/Prepaid 


Yes/ 
One 




Container 


Return charges must be prepaid. 


RetumRequest/Shipment/ 

Paymentlnformation/Prepaid/ 

BillShipper 


Yes/ 
One 




Container 


Return charges must be billed to 
the shipper. 


RetumRequest/Shipme nt/ 
Payme ntlnformation/Prepaid/ 
BillShipper/AccountNumber 


Yes/ 
One 


#PCDATA 


6 


UPS Account number. 
Valid lengths are 6 . 


RetumRequest/Shipment/ 
Service 


Yes/ 
One 




Container 


The UPS service selected for a 
return. 
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Table 1: Return Request Input 



ReturnRequest/Shipment/ 
Service/Code 


Yes/ 
One 


# PCDATA 


2 


Valid values are: 
'01' = Next Day Air, 

02 = 2 nd Day Air, 
'03'= Ground, 

1 £ = 6 Day belect, 


RetumRequest/Shipment/ 
RetiimService 


Yes/ 
One 




Container 


Type of Return service. 


RetumRequest/Shipment/ 
RetumService/ Code 


Yes/ 
One 


#PCDATA 


1 


Return Service types: 

'3' = UPS 1 -Attempt, 

*4' = UPS Print Return Label, 

'5'= UPS 3 -Attempt. 


RetumRequest/Shipment/ 
Package 


Yes/ 
One 




Container 


Package defines the package that 
is either to be returned. 


RetumRequest/Shipment/ 
Package/PackagingType 


Yes/ 
One 




Container 


Type of packaging in which the 
goods being shipped are packed. 


RetumRequest/Shipment/ 
Package/PackagingType/Code 


Yes/ 
One 


#PCDATA 


2 


Package types. Values are: 

4 0r= UPS Letter, 

'02' = Customer Supplied 

Package, 

'03'= Tube, 

'04'= Pak, 

*2 1 ' = UPS Express Box 


RetumRequest/Shipment/ 
Package/Description 


Yes/ 
One 


#PCDATA 


1..35 


Merchandise description of 
package. 


RetumRequest/Shipment/ 
Package/Dimensions 


No/ 

Zero or One 




Container 


The physical dimensions of an 
object. 

Length + 2 * (Width+ Height) must 
be less than or equal to 130 IN 


RetumRequest/Shipment/ 

Package/Dimensions/ 

UnitOfMeasurement 


Yes/ 
One 




Container 


Unit of measurement for the 
element that contains it 


RetumRequest/Shipme nt/ 
Package/Dime nsions/ 
UnitOfMe asurement/ Code 


Yes/ 
One 


#PCDATA 


2 


Package dimensions measurement 

code. Codes are: 

'IN' = Inches, 

'01'= English Units of 

Measurement. 
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Table 1: Return Request Input 



RetumRequest/Shipme nt/ 
Package/Dimensions/Length 


Yes/ 
One 


#PCDATA 


9 


Package length. 

Refer to the Universal Rules table 
in Appendix C. 

Required if width and height are 
set 

Valid values are 0 to 108 IN 










RetumRequest/Shipment/ 
Package/DimensioiWWidth 


Yes/ 
One 


#PCDATA 


9 


Package width. 

Refer to the Universal Rules table 
in Appendix C. 


RetumRequest/Shipment/ 
Paclopp/Oimp nsi nirs/rip 1 q ht 


Yes/ 
One 


#PCDATA 


9 


Package height. 

Refer to the Universal Rules table 

in Appendix C. 

Valid values are 0 to 330 IN. 


RptumReauest/Shinment/ 
Package/Package Weight 


Cond/ 
One 




Container 


Required when the package type is 
not UPS Letter. 


RetumRequest/Shipment/ 
Package/Package Weight/ 
UmtOfMeasurement/Code 


Yes/ 
One 


#PCDATA 


3 


Package weight unit of 
measurement code. Codes are: 
'LBS' = Pounds, 
'01' = English Unit of 
Measurements 


RetumRequest/Shipme nt/ 
Package/Package Weight/ 
Weight 


Yes/ 
One 


#PCDATA 


8 


Packages weight. 

Default to 0 for package type of 

UPS letters. 


RetumRequest/Shipment/ 
Package/ Overs izePackage 


No/ 

Zero or One 


#PCDATA 


1 


Oversize indicator 

Values are 

'0'= not oversized, 

T= OS1, 

'2' = OS2. 

Defaults to *0\ 

Refer to the Universal Rules table 
in Appendix C. 


RetumRequest/Shipment/ 
Package/ReferenceNumber 


No/ 

Zero to two 




Container 


Package-level reference numbers. 


RetumRequest/Shipment/ 
Package/Refere nceNumber/ 
Code 


No/ 

Zero or One 


#PCDATA 


2 


Reflects what will go on the label. 
Refer to Reference # Code Table. 


RetumRequest/Shipment/ 

Package/ReferenceNumber/ 

Value 


Yes/ 
One 


#PCDATA 


1..35 


Customer supplied reference 
number. 

Reference numbers are defined by 
the shipper and can contain any 
character string. 
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Table 1: Return Request Input 



RetumRequest/Shipment/ 
rackage/Additionalriandling 


No/ 

Lero or Une 


# EMPTY 


0 


The presence indicates additional 

1 kCXl i\_Llll Xif lCUUilCU r LI MS £UJ >>C 1 IV, C 

indicates no additional handling is 
required. 


ReturnRequest/Shipme nt/ 
Package/ 

PackageServiceOptions 


No/ 

Zero or One 




Container 


Defines service options available 
for packages. 


ReturnRequest/Shipment/ 
Package/ 

Package Se rviceOnfinrK/ 
InsuredValue 


No/ 

Zero or One 




Container 


Monetary value of the package. 


RetumRequest/Shipment/ 
Package/ 

Packai?eServiceOotifiris/ 
InsuredValue/CurrencyCode 


Yes/ 
One 


#PCDATA 


3 


Declared value amount currency 
type. 

Valid value must be ' USD' 


RetumRequest/Shipment/ 
Package/ 

Package Se rviceOotions/ 
InsuredValue/MonetaryValue 


Yes/ 
One 


#PCDATA 


1..19 


Insured value amount. 
Will accept insured value of 
$999.00 USD or less. 


RetumRequest/Shipment/ 
Package/ 

Package Se rvice Options/ 
Notification 


No/ 

Zero to One 




Container 


Container for the Return 
Notification accessorial. 
One RetumNotification per 
shipment. 


RetumRequest/Shipment/ 
Package/ 

PackageServdceOptions/ 
Notification/NotificationCode 


Yes/ 
One 


#PCDATA 


1 


The type of shipment notification 

requested. 

Valid Value: 

3 = Return Notification 


RetumRequest/Shipment/ 
Package/ 

PackageServiceOptions/ 
Notification/EMailMessage 


Yes/ 
One 




Container 


Container for the e-mail Message. 


ReturnRequest/Shipme nt/ 
Package/ 

PackageServiceOptions/ 

Notification/EMailMessage/ 

EMailAddress 


Yes/ 

One or two 


#PCDATA 


1..50 


The destination eMail address of 
the return notification eMail. 
Refer to the Universal Rules table 
in Appendix C. 
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Table 1: Return Request Input 



RetumRequest/Shipment/ 
Package/ 

PackageServiceOptions/ 

Notification/EMailMessage/ 

UndeliverableEMailAddress 


No/ 

Zero or One 


#PCDATA 


1..50 


The e-mail address where an 
undeliverable eMail message is 
sent if the Return Notification 
email is undeliverable. 
Refer to the Universal Rules table 
in Appendix C. 

Defaults to FromEMailAddress. 


KetuniJKequest/Dhipment/ 
Package/ 

PackageServiceOptions/ 

Notification/EMailMessage/ 

FromEMailAddress 


Yes/ 
One 


J1¥"W~*T^ ATA 

#FLDA1A 


I ..50 


The e-mail address specifies the 
From E-mail address. 
Refer to the Universal Rules table 
in Appendix C. 


RetumRequest/Shipment/ 
Package/ 

PackageServiceOptions/ 

Notification/EMailMessage/ 

FromName 


No/ 

Zero or One 


#PCDATA 


1..35 


The name the return notification 
will appear to be from. 
Defaults to the Shipper Name 


RetumRequest/Shipment/ 
Package/ 

PackageServiceOptions/ 

Notification/EMailMessage/ 

iviemo 


No/ 

Zero or One 


#PCDATA 


1..150 


User defined text that will be 
included in the eMail. 


RetumRequest/Shipment/ 
Package/ 

PackageServiceOptions/ 

i\J rtri fi r*s»ri nn / H n/lc* i 1 nAt* cc n or *> / 
iXUlillCclLlUl v l^vicUJUVie^oogc/ 

Subject 


No/ 

Zero or One 


#PCDATA 


1..75 


The eMail's subject. Defaults to 
the 'Return Notification' plus the 
shipment ID. 

lJ#*fiai ilte tc\ tf*vt nmviHprl lrv 1 IPS 

L/CldUlU UU ICAl UIUVIUCU UV KJ1 \J 


RetumRequest/Shipment/ 
Package/ 

PackageServiceOptions/ 
LabelDe livery 


No/ 

Zero or One 




Container 


Container for the Label Delivery 
accessorial. 

One Label Delivery per shipment 


ReturnRequesl/Shipment/ 
Package/ 

PackageServiceOptions/ 
LabelDelivery/EMailMessage 


Yes/ 
One 




Container 


Container for the eMail message. 


RetumRequest/Shipment/ 
Package/ 

PackageServiceOptions/ 

LabelDelivery/EMailMessage/ 

EMailAddress 


Yes/ 
One 


#PCDATA 


1..50 


The destination eMail address for 
the Label Delivery. 
Refer to the Universal Rules table 
in Appendix C. 
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Table 1 : Return Request Input 



RetumRequest/Shipmenl/ 
Package/ 

PackageServiceOptions/ 

LabelDekvery/hMailMessage/ 

UndeliverableEMailAddress 


No/ 

Zero or One 


#PCDATA 


1..50 


The address where an 
undeliverable eMail message is 
sent if the Label Delivery email is 
1 1 nH p 1 ivp rahlp 

Ul i V_J. ^ U. VvlQUlv * 

Refer to the Universal Rules table 
in Appendix C. 

Defaults to FromEMailAddress. 


RetumRequest/Shipmenl/ 
Package/ 

PackageServiceOptions/ 
LabelDelivery/ 
EMailMessage/ 
FromEMailAddress 


Yes/ 
One 


#PCDATA 


1..50 


The e-mail address specifies the 

1 1 Uli 1 i_i IIlcLU dUUlcso. 

Refer to the Universal Rules table 
in Appendix C. 


RetumRequest/Shipment/ 
Package/ 

PackageServiceOptions/ 
LabelDe live ry/EMailMess age/ 
FromName 


INo/ 

Zero or One 




1 ..OJ 


ine name nouncanori win appecii 
to be from. Defaults to the Shipper 
Name 


KetumKequesuonipment/ 
Package/ 

PackageServiceOptions/ 
LabelDe UveryEMailMessage/ 
Memo 


INO/ 

Zero or One 


APTTIATA 


1 ..1 JU 


user ueiuicu ujaj. ukiL win ue 
included in the eMail. 


RetumRequest/Shipment/ 
Package/ 

PackageServiceOptions/ 

LabelDelivery/EMailMessage/ 

Subject 


No/ 

Zero or One 


#PCDATA 


1.75 


The eMail 9 a subject. Defaults to 
the 1 Label Delivery Notification 
plus the shipment ID. 
Defaults to text provided by UPS 


RetumRequest/Shipment/ 
ShipmentServiceOptions 


No/ 

Zero or One 




Container 


Optional UPS services related to a 
shipment. 


RetumRequest/Shipment/ 

ShipmentServiceOptions/ 

Notification 


No/ 

Zero to one 




Container 


Container for the Pickup 
Notification accessorial. 
One Pickup per shipment 


RetumRequest/Shipme nt/ 
ShipmentServiceOptions/ 
Notification/ 
NotificationCode/ 


Yes/ 
One 


#PCDATA 


1 


The type of shipment notification 

requested. 

Valid Value: 

2 = Pickup Notification 


RetumRequest/Shipment/ 

ShipmentServiceOptions/ 

Notification/EMailMessage 


Yes/ 
One 




Container 


Container for the eMail message. 
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Table 1: Return Request Input 



RetumRequest/Shipment/ 
ShipmentServdceOptions/ 
Notification/EMailMessage/ 
EMailAddress 


Yes/ 
One 


#PCDATA 


1..50 


Hie destination eMail address for 
the eMail with the Pickup 
Notification. 

Refer to the Universal Rules table 
in Appendix C. 


RetumRequest/Shipment/ 
ShipmentServiceOptions/ 
Notification/EMailMessage/ 
FromEMailAddress 


Yes/ 
One 


#PCDATA 


1..50 


The e-mail address specifies the 
rrom rL-mail address. 
Refer to the Universal Rules table 
in Appendix C. 


RetumRequest/Shipment/ 
ShipmentServiceOptions/ 
JNotincauoiVrJVlmlMessage/ 
UndeliverableEMailAddress 


No/ 
One 


#PCDATA 


1..50 


The address where an 
undeliverable eMail message is 
sent if the eMail with the 
notification is undeliverable. 
Defaults to the FromEMailAddress 
Refer to the Universal Rules table 
in Appendix 0. 


RetumRequest/Shipment/ 
ShipmentServiceOptions/ 
Notification/EMailMessage/ 
FmmNamp 


No/ 

Zero or One 


#PCDATA 


1..35 


The name the email will appear to 
be from. Defaults to the Shipper 
Name 

Name. 


RetumRequest/Shipment/ 
ShipmentServiceOptioris/ 
Notification/EMailMessage/ 
Memo 


No/ 

Zero or One 


#PCDATA 


1..150 


User defined text that will be 
included in die eMail. 


RetumRequest/Shipment/ 
ShipmentServdceOptions/ 
Notification/EMailMessage/ 
Subject 


No/ 

Zero or One 


#PCDATA 


1..75 


The eMail's subject. Defaults to 
the Pickup Notification plus the 
shipment ED. 

Defaults to text provided by UPS 



Return Request Example 

<?xml version = "L0"?> 
<AccessRequest> 

<AccessLicenseNumber>5B53 1 C247568B520</AccessLicenseNumber> 

<UserId>JohnQPublic</UserId> 

<Password>p@$$ w *rd</Password> 
</AccessRequest> 
<?xml version = M 1.0 M ?> 
<RetumRequest> 

<Request> 

<RequestAction>Retum</RequestAction> 
<TransactionReference> 

<CustomerContext/> 
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<XpciVersion Version = M l .0002 M /> 
</TransactionReference> 
</Request> 
<LabelSpecification> 

<LabelPrintMethod> 

<Code>GIF</Code> 
</LabelPrintMethod> 
<LabelStockSize> 

<Height>8</Height> 

<Width>4</Width> 
</LabelStockSize> 

<HTTPUserAgent>Mozilla/4.5</HTTPUserAgent> 

<LabelImageFormat> 

<Code>GIF</Code> 

</LabelImageFormat> 
</LabelSpecification> 
<Shipment> 

<Shipper> 

<Name>Merchant</Name> 
<PhoneNumber>800555 1 2 1 2</PhoneNumber> 
<ShipperNumber>abc 1 23</ShipperNumber> 
<Address> 

< AddressLine 1 > 1 1 Merchant Lane</AddressLine 1 > 
<City>Atlanta</City> 

<StateProvinceCode>GA</StateProvinceCode> 
<PostalCode>301 88</PostalCode> 
<CountryCode>US</CountryCode> 
</Address> 

</Shipper> 

<ShipTo> 

<CompanyName>Vendor</CompanyName> 
<AttentionName>ContactName</AttentionName> 
<PhoneNumber>8009 1 90000</PhoneNumber> 
<Address> 

< AddressLine 1>33 Vendor Lane</AddressLinel> 
<City>Atlanta</City> 

<StateProvinceCode>GA</StateProvinceCode> 
<PostalCode>300 1 8</PostalCode> 
<CountryCode>US</CountryCode> 
</Address> 
</ShipTo> 
<ShipFrom> 

<CompanyName>Jane Doe</CompanyName> 

<PhoneNumber>5551414</PhoneNumber> 

<Address> 

<AddressLinel>2001 Consumer Drive</AddressLinel> 
<City>Atlanta</City> 

<StateProvinceCode>GA</StateProvinceCode> 
<PostalCode>300 10</PostalCode> 
<CountryCode>US</CountryCode> 
</Address> 
</ShipFrom> 
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<RetumService> 

<Code>4</Code> 
</ReturnService> 
<Service> 

<Code>0K/Code> 
</Service> 

<PaymentInfonnation> 
<Prepaid> 

<BillShipper> 

<AccountNumber> 1 23456</AccountNumber> 
</BillShipper> 
</Prepaid> 
</PaymentInformation> 
<Package> 

<PackageServiceOptions> 
<Notification> 

<NotificationCode>3</NotificationCode> 
<EMailMessage> 

<EMailAddress>Vendor@vendor.com</EMailAddress> 
<Memo/> 

<Subject>Shipment ID</Subject> 

<FromEMailAddress>Shipper@shipper.com</FromEMailAddress> 
<FromName>Merchant</FromName> 

<UndeliverabIeEMailAddress>Shipper@shipper.com</UndeliverableEMailAddress> 
</EMailMessage> 
</Notification> 
</PackageServiceOptions> 
<AdditionalHandling/> 
<ReferenceNumber> 

<Code>75</Code> 
<Value>0123456789</Value> 
</ReferenceNumber> 

<Description>Letter to be returned</Description> 
<PackagingType> 

<Code>01</Code> 
</PackagingType> 
</Package> 
</Shipment> 
</ReturnRequest> 
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Return Response Output 



DID Definition 

< ! ELEMENT RetiimResponse (Response , ShipmentResults? )> 
Table 2: Return Response Outputs 



Name (Xpath) 



Required/ 
Cardinality Type 



Length Description/Values 



RetumResponse/Response/ 

TransactionReference/ 

CustomerContext 


No 


Any 


0..512 


Customer provided data. 
May be XML. If this data is 
present in the request, it is 
echoed back to the customer. 


Rpti irriRpsr>nrisp/Rp<ir»rin<;p/ 

TransactionReference/ 
XPCIVersion 


No 


A lnK?ini imp rip 


1..50 


Tripntifies thp vpr*»inn of thp 
message. Current version is 
1.0002 


RetumResponse/Response/ 
ResponseStatusCode 


Yes 


Numberic 


1 


Identifies the success or 
failure of the interchange. 
1 = Success 
0 = Failure 


RetumResponse/Response/ 
ResponseStatusDescription 


No 


Alphanumeric 


1..15 


Describes the Response 
Status Code. 


RetumResponse/Response/ 
Error 


No 




Container 


If an error is encountered 
during the interchange, the 
Response contains an error. 
If the error is present, men 
the ErrorSe verity and 
ErrorCode are required. 


RetumResponse/Response/ 
Error/ErrorSe ve rity 


Yes 


Alphanumeric 


1..15 


Describes the severity of the 
error. 


RetumResponse/Response/ 
Error/ErrorCode 


Yes 


Numberic 


1..15 


A numberic value that 
describes the error. Each 
tool defines a range of error 
codes. Refer to error 
conditions, in the 
appropriate chapter, for a 
complete list of interchange 
errors. 


RetumResponse/Response/ 
Error/ErrorDescription 


No 


Alphanumeric 


1..50 


Describes the error code. 
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Returns on the Web 



Table 2: Return Response Outputs 



RetumResponse/Response/ 
Erroi/MinimumRetiySeconds 


No 


Numeric 


1..5 


Number of seconds to wait 
until retry. This field is 
populated on special 
conditions of the Transient 
Error only, as defined by the 

jCI V1LC • 

A number between 1 and 
86400 (24 hours) 


RetumResponse/Response/ 
ErrorLocation 


No 




Container 


Identifies the element in 
error. 


RetumResponse/Response/ 

ErrorLocation/ 

ErrorLocationElementName 


No 


Alphanumeric 


1.512 


The Xpath name of the 
element in error. This is a 
valid Xpath pointing to an 
element in the request 
document. 


RetumResponse/Response/ 

ErrorLocation/ 

ErrorLocationAttributeName 


No 


Alphanumeric 


1..50 


The name of the attribute in 
error. This is the name of 
the attribute contained by the 
Error Location element 


RetumResponse/Response/ 
ErrorLocation/ErrorDigest 


No 


Alphanumeric 


Bound by 
the size of 
the Request 
data. 


The contents of the element 
in error. 


RetumResponse/ 
ShipmentResults 


Yes/ 
One 




Container 


Processed shipment 
information returned from 
RetumRequest. 


RetumResponse/ 
ShipmentResults/ 
ShipmentCharges 


Yes/ 
One 




Container 


Changes breakdown for a 
shipment 


RetumResponse/ 
ShipmentResults/ 
ShipmentCharges/ 
TransportationCharges 


Yes/ 
One 




Container 


Base charges incurred by a 
return to move it from the 
origin address to the 
destination address. 


RetumResponse/ 

ShipmentResults/ 

ShipmentCharges/ 

TransportationCharges/ 

CurrencyCode 


Yes/ 
One 


#PCDATA 


3 


Transportation charges 
currency code type. The 
currency code used in the 
RetumRequest is returned. 
The only value that will be 
returned is ' USD' 
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Table 2: Return Response Outputs 



RetumResponse/ 

ShipmentResults/ 

ShipmentChanjes/ 

TraraportationCharges/ 

MonetaryValue 


Yes/ 
One 


#PCDATA 


1..19 


Transportation and 
surcharges value amount. 
Valid values are from 0 to 
9999999999999999 
(sixteen 9's) 


RetumResponse/ 
ShipmentResults/ 
ShipmentChanjes/ 
ServiceOptionsCharges 


Yes/ 
One 




Container 


The cost related to the 
service options for packages 
and shipments. 


RetumResponse/ 

ShipmentResults/ 

ShipmentChanjes/ 

ServdceOptionsCharges/ 

CurrencyCode 


Yes/ 
One 


#PCDATA 


3 


Option charges currency 
code type. Hie currency 
code used in the 
RetumRequest is returned. 
The only value returned is 
USD 


RetumResponse/ 

ShipmentResults/ 

ShipmentChanjes/ 

ServiceOptioraCharges/ 

MonetaryValue 


Yes/ 
One 


#PCDATA 


1..19 


Option charges value 
amount 

Valid values are from 0 to 
9999999999999999 
(sixteen 9s) 


RetumResponse/ 
ShipmentResults/ 
ShipmentChanjes/ 
TotalCharges 


Yes/ 
One 




Container 


Total charges for a return. It 
includes transportation cost 
as well as service option 
costs. 


RetumResponse/ 

ShipmentResults/ 

ShipmentChanjes/ 

TotalCharges/ 

CurrencyCode 


Yes/ 
One 


#PCDATA 


3 


Total charges currency code 
type. The currency code 
used in the RetumRequest is 
returned. 

The only value returned is 
USD' 


RetumResponse/ 

ShipmentResults/ 

ShipmentChanjes/ 

TotalCharges/ 

MonetaryValue 


Yes/ 
One 


#PCDATA 


1..19 


Total charges value amount. 
Valid values are from 0 to 
9999999999999999 
(sixteen 9s) 


RetumResponse/ 
ShipmentResults/ Billing Weight 


Yes/ 
One 




Container 


The weight used for rate 
calculation. This varies from 
the actual weight when the 
package dimensions causes 
dimensional weight or 
oversized weight rating 
calculation to occur. 
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Table 2: Return Response Outputs 



RetumResponse/ 
ShipmentResults/ 
BillingWeight/ 
UnitDflVleasurement 


Yes/ 
One 




Container 


Unit of measurement for the 
element that contains it. 


RetumResponse/ 
ShipmentResults/ 
BillingWeight/ 
UnitOfMe as ure me nt/ 

Code 


Yes/ 
One 


#PCDATA 


2..3 


Billing weight unit of 
measurement code. The unit 
of measurement used in 
RetumRequest is returned. 
Unit of Measurement 
defaults to the shippers 
country 

Valid value to be returned is 
XBS' 


RetumResponse/ 

ShipmentResults/ 

BillingWeight/ 

UnitOfMeasurement/ 

Description 


No/ 

Zero or One 


#PCDATA 


3 


Description of the billing 
weight measurement units. 
Value returned is: ' LBS' 


RetumResponse/ 
ShipmentResults/ 
BillingWeight/Weight 


Yes/ 
One 


#PCDATA 


8 


Billing weight Higher of the 
actual shipment weight 
versus the shipment 
dimensional weight. Set to 0 
for package type of letters or 
envelopes. 

Will not exceed 150LBS. 


RetumResponse/ 
ShipmentResults/ 
ShipmentldentificationNumber 


Yes/ 
One 


#PCDATA 


18 


Returned UPS shipment ID 
number. 

Tracking Number of the first 
package in the shipment. 


RetumResponse/ 
ShipmentResults/ 
PackageResults 


Yes/ 

One or more 




Container 


Returned Package 
Information. 


RetumResponse/ 
ShipmentResults/ 
PackageResults/ 
TrackingNumber 


Yes/ 
One 


#PCDATA 


18 


Package Tracking number. 


RetumResponse/ 
ShipmentResults/ 
PackageResults/ 
ServiceOptionsChanjes 


Cond/ 

Zero or One 




Container 


Shipment charges info. 
Shipment charges are only 
guaranteed to be returned 
for shipments whose origin 
country is US. 
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RetumResponse/ 
Shipme ntResults/ 
PackageResults/ 
ServiceOptionsCharges/ 
CurrencyCode 


Yes/ 
One 


#PCDATA 


3 


Package accessorial charges 
currency code type. The 
currency code used in the 
RetumRequest is returned. 

The only value to be 
returned is UoU 


RetumResponse/ 

ShipmentResults/ 

PackageResults/ 

SendceOptionsCharges/ 

MonetaiyValue 


Yes/ 
One 


#PCDATA 


1..19 


Package accessorial charges 

value amount. 

Valid values are from 0 to 

9999999999999999 

(sixteen 9s) 


RetumResponse/ 
ShipmentResults/ 
PackageResults/ 
TramportationCharges 


Yes/ 
One 




Container 


Base charges incurred by a 
return to move it from the 
origin address to the 
destination address. 


RetumResponse/ 

ShipmentResults/ 

PackageResults/ 

TramportationCharges/ 

CurrencyGxle 


Yes/ 
One 


#PCDATA 


3 


Transportation charges 
currency code type. The 
currency code used in the 
RetumRequest is returned. 
The only value to be 
returned is 1 USD* 


RetumResponse/ 

ShipmentResults/ 

PackageResults/ 

TransportationCharges/ 

MonetaiyValue 


Yes/ 
One 


#PCDATA 


1..19 


Transportation and 
surcharges value amount. 
Valid values are from 0 to 
9999999999999999 
(sixteen 9s) 


RetumResponse/ 
ShipmentResults/ 
PackageResults/ 
Labellmage 


i\o/ 

One or Zero 




v_xjncainer 


l rie elements neeueu uj 
render a label on a printer or 
in a browser. Specifies the 
format in which 
Graphiclmage is 
represented. If 
LabellmageFormat is GIF, 
Labellmage contains 
Graphiclmage and 
HTMLImage. Otherwise, it 
contains only Graphiclmage. 


RetumResponse/ 
ShipmentResults/ 
PackageResults/ 
Labellmage/ 
Labellmage Format 


Yes/ 
One 




Container 


The format of a label image 
byte stream. 
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Table 2: Return Response Outputs 



RetumResponse/ 
ShipmentResults/ 
Package Results/Labe llmage/ 
LabellmageFormat/ Code 


Yes/ 
One 


#PCDATA 


3 


Label image code that the 
labels are generated. Values 
TEPL' = EPL2, 4 GIF= gif 
images . 

Only 'EPL' and 'GIF' are 
currently supported. 


RetumResponse/ 

ShipmentResults/ 

PackageResults/Labellmage/ 

LabellmageFormat/ 

Description 


No/ 
One 


#PCDATA 


L.35 


Description of the label 
image format code. 


RetumResponse/ 
ShipmentResults/ 
PackageResults/Labellmage/ 
Graphiclmage 


Yes/ 
One 


Base 64 
Encoded 


Variable 
Length 


Base 64 encoded graphic 
image. 


RetumResponse/ 
ShipmentResults/ 
PackageResults/Labellmage/ 
HlMLImage 


Cond/ 

Zero or One 


Base 64 
Encoded 


Variable 
Length 


Base 64 encoded html 
browser image rendering 
software. 

This is only returned for gif 
image formats. 



Return Response Example 

<?xml version = "1.0"?> 
<ReturnResponse> 

<Response> 

<TransactionReference> 

<CustomerContext> 

<Xpci Version Version = M 1.0002 M /> 
</CustomerContext> 
</TransactionReference> 
<ResponseStatusCode> 1 </ResponseStatusCode> 
<ResponseStatusDescription>Success</ResponseStatusDescription> 
</Response> 
<ShipmentResults> 

<ShipmentCharges> 

<TransportationCharges> 

<CurrencyCode>USD</CurrencyCode> 
<Monetary Value>3 .50</Monetary Value> 
</TransportationCharges> 
<ServiceOptionsCharges> 

<CurrencyCode>USD</CurrencyCode> 
<Monetary Value>3 . 5 0</Monetary Value> 
</ServiceOptionsCharges> 
<TotalCharges> 

<CurrencyCode>USD</CurrencyCode> 
<MonetaryValue>7.00</MonetaryValue> 
</TotalCharges> 
</ShipmentCharges> 
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<BillingWeight> 

<UnitOfMeasurement> 

<Code>LBS</Code> 

</UnitOfMeasurement> 

<Weight>0</Weight> 
</BillingWeight> 

<ShipmentIdentificationNumber> 1 Z 1 23BDS456 1 268F9L</ShipmentIdentificationNumber> 
<PackageResuits> 

<TrackingNumber> 1 Z 1 23BDS456 1 268F9L</TrackingNumber> 
<TransportationCharges> 

<CurrencyCode>USD</CurrencyCode> 
<MonetaryValue>3 .50</Monetary Value> 
</TransportationCharges> 
<ServiceOptionsCharges> 

<CurrencyCode>USD</CurrencyCode> 
<Monetary Value>3 .50</Monetary Value> 
</ServiceOptionsCharges> 
<TotalPackageCharges> 

<CurrencyCode>USD</CurrencyCode> 
<MonetaiyValue>7.00</MonetaryValue> 
</TotalPackageCharges> 
</PackageResults> 
</ShipmentResults> 
</ReturnResponse> 

Return Notification E-mail 

When the Consumer requests a return, the Vendor is supplied a Return Notification. The return notification e 
mail will contain the XML provided in the table below. 

DTD Definition 

< IELEMENT RetiirnNotificationEMail (Shipper , ShipFrom, ShipTo, MerchandiseDescription, 
ReferenceNumber, TrackingNumber)> 

Table 3: Return Notification 



Required/ 

Name (Xpath) Cardinality Type Length Description/Value 



RetumNotfficatioiiEMail/ 
Shipper 


Yes/ 
One 




Container 


Shipper of record for a 
shipment. 


ReturnNotificationEMail/ 
Shipper/Name 


Yes/ 

Zero or One 


#PCDATA 


1..35 


Shippers company name. 


ReturnNotificationEMail / 
Shipper/AttentionName 


No/ 

Zero or One 


#PCDATA 


1..35 


Shipper s Attention Name 


ReturnNotificationEMail/ 
Shipper/ Address 


Yes/ 
One 




Container 


Information that specifies a 
physical location. 
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Table 3: Return Notification 



RetumNotificationEMail/ 
Shipper/ Address/ 
AddressLinel 


Yes/ 
One 


# PCDATA 


1..35 


Address Line 1 of the 
shipper. 


RetumNotificationEMail/ 
Shipper/ Address/ 
AddressLine2 


No/ 

Zero or One 


#PCDATA 


1..35 


Address Line 2 of the 
shipper. Usually Room/Floor 
information . 


RetumNotificationEMail/ 
Shipper/ Address/ 
AddressLine3 


No/ 

Zero or One 


#PCDATA 


1..35 


Address Line 3 of the 
shipper. Usually department 
information . 


RetumNotificationEMail/ 
Shipper/ Address/ City 


Yes/ 
One 


#PCDATA 


1..30 


Shipper's city. 


RetumNotificationEMail/ 
Shipper/ Address/ 
State Province Code 


Yes/ 
One 


#PCDATA 


2 


Shipper's state code. 
Must be a valid US State 


Rph lmNntifirationFMail/ 
Shipper/ Address/ 
PostalCode 


Yes/ 
One 


# PCDATA 


5,9 


Shipper's postal code. 
5 or 9 digits are required. 


RetumNotificationEMail / 
Shipper/ Address/ 
CountryCode 


Yes/ 
One 


#PCDATA 


2 


Shipper's country code. 
Valid value must be: 'US' 


RetuiriNotificationEMail/ 
ShipTo 


Yes/ 
One 




Container 


Address and contact 
information describing the 
location where a return is to 
be delivered. 


RetumNotificationEMail/ 
ShipTo/CompanyName 


Yes/ 
One 


#PCDATA 


1..35 


Consignee's company name. 


RetumNotificationEMail/ 
ShipTo/AttentionName 


Yes/ 

Zero or One 


#PCDATA 


1..35 


Contact name at the 
consignee's location. 


RetumNotificationEMail/ 
ShipTo/Address 


Yes/ 
One 




Container 


Information that specifies a 
physical location. 


RetumNotificationEMail/ 

ShipTo/Address/ 

AddressLinel 


Yes/ 
One 


# PCDATA 


1..35 


Address Line 1 of the 
consignee. 


RetumNotificationEMail/ 

ShipTo/Address/ 

AddressLine2 


No/ 

Zero or One 


# PCDATA 


1..35 


Address Line 2 of the 
consignee. Usually Room/ 
Floor information. 


RetumNotificationEMail/ 

ShipTo/Address/ 

Ad dress Line 3 


No/ 

Zero or One 


# PCDATA 


1..35 


Address Line 3 of the 
consignee. Usually 
department information. 
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Table 3: Return Notification 



RetumNotificationEMail/ 
ShipTo/ Address/ City 


Yes 
One 


#PCDATA 


1..30 


Consignee's city. 


RetumNotificationEMail/ 
ShipTo/Address/ 
StateProvince Code 


Yes 
One 


#PCDATA 


2 


Must be a valid US State 


RetumNotificationEMail/ 

ShipTo/Address/ 

PostalCode 


Yes 
One 


#PCDATA 


5,9 


Consignee's postal code. 
5 or 9 digits are required. 


Tcofi i (vlrit t f i ni i #vn H 1x71 oil/ 

rveiuii uNouncaiioixi-jivicUi/ 

ShipTo/Address/ 

CountryCode 


Vpc 

One 


#PCDATA 


2 


Consignee's country code. 
Valid value must be: 1 US' 


J?c»t-i i rt-iMi-k+ifi^ofi r-ir% T^A/f oil/ 

jxeujjTuNOuncauoiTCaviaii/ 
ShipFrom 


i es 
One 




Contyiinpr 


Addre<is and contact 
information describing the 
location where a shipment is 
to be picked up. 


RetumNotificationEMail/ 

ShipFrom/ 

CompanyName 


Yes 
One 


#PCDATA 


1..35 


Consumer s company name. 


RetumNotificationEMail/ 

ShipFrom/ 

AttentionName 


No 

Zero or One 


#PCDATA 


1..35 


Contact name. 


RetumNotificationEMail/ 
ShipFrom/ Address 


Yes 
One 




Container 


Information that specifies a 
physical location. 


ReturnNotificationEMail/ 
ShipFrom/ Address/ 
AddressLinel 


Yes 
One 


#PCDATA 


1..35 


Address Line 1 of the pickup 
location. 


RetumNotificationEMail/ 
ShipFrom/ Address/ 
AddressLineZ 


No 

Zero or One 


#PCDATA 


1..35 


Address Line 2 of the pickup 
location. Usually Room/Floor 
information. 


RetumNotificationEMail/ 

ShipFrom/Address/ 

AddressLine3 


No 

Zero or One 


#PCDATA 


1..35 


Address Line 3 of die pickup 
location. Usually department 
information. 


RetumNotificationEMail/ 
ShipFrom/Address/Ciry 


Yes 
One 


#PCDATA 


1..30 


Pickup location's city. 


RetumNotificationEMail/ 
ShipFrom/Address/ 
State Province Code 


Yes 
One 


#PCDATA 


2 


Pickup location's state code. 
Must be a valid US State. 
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Table 3: Return Notification 



RetumNotificationEMail/ 
bhipr rom/ Address/ 
PostalCode 


Yes 
One 


#PCDATA 


5,9 


Pickup location's postal 
code . 

5 or 9 digits are required. 


RetumNotificationEMail/ 
ShipFrom/ Address/ 
CountryCode 


Yes 
One 


# PCDATA 


2 


Pickup location's country 
code. 

Valid value must be: ' US' 


RetumNotificationEMail/ 
Description 


Yes 
One 


#PCDATA 


1..35 


Description of the goods 
being returned. 


RetumNotificationEMail/ 
ReferenceNumber 


Yes 

Zero to Two 




Container 


Package-level reference 
numbers. 


RetumNotificationEMail/ 
Reference Number/ Code 


Yes 
One 


#PCDATA 


2 


Reflects what will go on the 
label. 

rverer to rveiererice tr vxxjtj 
Table 


Rpti imlVntifirpiHnnPMiiil/ 

AVC LULL 1 11 lUUHLuLlUl I.I -ilVICi.il/ 

ReferenceNumber/V alue 


Yes 
One 


#PCDATA 

II A Vyl^il lift 


1..35 


Customer supplied reference 
number. 

Reference numbers are 
defined by the shipper and 
can contain any character 
string. 


RetumNotificationEMail/ 
TrackingNumber 


Yes 
One 


#PCDATA 


18 


Package Tracking Number 


RetumNotificationEMail/ 
Package Weight 


Cond 

Zero or One 




Container 


Returned when the package 
type is not UPS Letter. 


RetumNotificationEMail/ 
Package Weight/ 
UnitofMeasurement 


Yes 
One 




Container 


Unit of measurement for the 
element that contains it. 


RetiimNotificationEMail/ 
PackageWeight/ 
UnitofMeasurement/ 
Gxie 


Yes 
One 


#PCDATA 


3 


Package weight unit of 

measurement code. Valid 

values are: 

'LBS* = Pounds 

'01' = English Unit of 

Measurements 


ReturnNotificationEMail/ 
Package Weight/Weight 


Yes 


#PCDATA 


8 


Packages weight. 
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Return Notification Example 

<?xml version = "1.0"?> 
<RetumNotificationEMail> 
<Shipper> 

<Name>Merchant</Name> 

<Address> 

<AddressLinel>l 1 Merchant Lane</AddressLinel> 
<City>Atlanta</City> 

<StateProvinceCode>GA</StateProvinceCode> 
<PostalCode>30 1 88</PostalCode> 
<CountryCode>US</CountryCode> 
</Address> 
</Shipper> 
<ShipFrom> 

<CompanyName>Jane Doe</CompanyName> 
<Address> 

<AddressLinel>2001 Consumer Drive</AddressLinel> 
<City>Atlanta</City> 

<StateProvinceCode>GA</StateProvinceCode> 
<PostalCode>300 1 0</PostalCode> 
<CountryCode>US</CountryCode> 
</Address> 

</ShipFrom> 

<ShipTo> 

<CompanyName>Vendor</CompanyName> 

<AttentionName>ContactName</AttentionName> 

<Address> 

<AddressLinel>33 Vendor Lane</AddressLinel> 
<City>Atlanta</City> 

<StateProvinceCode>GA</StateProvinceCode> 
<PostalCode>300 1 8</PostalCode> 
<CountryCode>US</CountryCode> 
</Address> 
</ShipTo> 
<ReferenceNumber> 

<Code>75</Code> 
<Value>0 1 23456789</Value> 
</ReferenceNumber> 

<TrackingNumber> 1 ZFOO 1 000997823970</TrackingNumber> 
<Description>PackageDescription</Description> 
</ReturnNotificationEMail> 



United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 



Returns on the Web 



UPS Label Recovery 



On occasion a customer will lose the label and call the Merchant to ask for another. The Merchant requests a 
duplicate label from UPS using the Returns on the Web XML Tool. 

The End Consumer submits a request to the Merchant to recover a return label, the Merchant then submits an 
XML Request to UPS. The request must contain either the Tracking Number, or a combination of the Shipper 
Number and a Reference Number. UPS then returns the Tracking Number along with a recovered label. 



End Consumer 



Merchant/ 
Shipper 



UPS 



1) Request Label 



2) XML Label 
Recovery Request 



4) Return Label 



3) XML Label 
Recovery Response 



Figure 4: Label Recovery Request/Response Process 

Label Recovery Request Input 
DTD Definition 

< IELEMENT LabelRecoveryRequest (Request , LabelSpecification? , (TrackmgNumber | 
(ReferenceNumber , ShipperNumber)))> 

Table 4: Label Recovery Request Input 



Name (Xpath) 


Required/ 
Cardinality Type 


Length 


Descri pt ion/Va 1 ue 


LabelRecoveryRequest/ 
Request 


Yes/ 
One 




Container 




LabelRecoveryRequest/ 
Request/RequestAction 


Yes/ 
One 


#PCDATA 


1.2 


Indicates the action to be taken 
by the XML service. 
Must be 

'LabelRecoveryRequest 1 . 


LabelRecoveryRequest/ 
Request/ TransactionRe fere nee 


No/ 
One 




Container 


TransactionReference identifies 
transactions between client and 
server. 
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Table 4: Label Recovery Request Input 



LabelRecoveryRequest/ 
Request/ TransactionReference/ 
Cus tome rContext 


No/ 

Zero to One 


#ANY 


1..50 


The client uses 
CustomerContext to 
synchronize request/response 
pairs. The client establishes 
CustomerContext, which can 
contain any information you 
want, as along as it is valid 
XML; it is echoed back by the 
server. 


LabelRecoveiyRequest/ 
Request/ TransactionReference/ 
XpciVersion 


No/ 

Zero to One 


#PCDATA 


4 


Message version. Defaults to 
T.0002'. 


LabelRecoveryRequest/ 
Request/Testlndicator 


No/ 

Zero to One 


EMPTY 


0 


Indicate the caller requests test 
behavior, if relevant, in which 
the processor may exhibit 
behavior different from 
production. The processor may 
ignore the request if no 
variation in behavior is 
available. 


LabelRecoveryRequest/ 
LabelSpecification 


No/ 

Zero to One 




Container 


Container used to define the 
properties required by the user 
to print and/or display the 
label. 

Should the user choose not to 
populate the fields, the 
LabelPrintMethod/Code will 
default to gif, HTIPUserAgent 
will default to Mozilla/4 .5 and 
LabellmageFormat/Code will 
default to gif. 


Labe lRe cove ryRequest/ 

LabelSpecification/ 

LabelPrintMethod 


Yoc/ 

i es/ 
One 




vxjniainer 


I Vio rlov/itf^o ncofl nrint ft IfirifM 
1 lie Uc Vltc lOcU UJ JJ11I1L a. laJJCI 

image. 


LabelRecoveryRequest/ 

LabelSpecification/ 

l^elPrintMethod/Code 


Yes/ 
One 


#PCDATA 


3 


Label print method code that 
the labels are to be generated 
for EPL2 formatted labels use 
*EPL' and for image formats 
use 'GIF*. 

Valid values are 'GIF' and 
'EPL\ 
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Table 4: Label Recovery Request Input 



LabelRecoveiyRequest/ 

LabelSpecification/ 

HTIPUserAgent 


Cond/ 

Zero or One 


#PCDATA 


1..64 


Browser HTIPUserAgent 
String. This is the preferred 
way of identifying GIF image 
type to be generated 
Required if RetumRequest/ 
LabelSpecification/ 
LabeLPrintMethod/Code = 
GIF. 


LabelRecove ry Re quest/ 

LabelSpecification/ 

LabelStockSize 


No/ 

/ £XTt\ nr 1 Inp 

I—XZ 1 KJ Ul W 1 




Container 


The size of the label stock used 
to render a label image. 


LabelRecoveiyRequest/ 

LabelSpecification/ 

LabelStockSize/Height 


Yes/ 
One 


#PCDATA 


1..3 


Width of the label image. For 
IN, use whole inches. 
For EPL2 labels only. 

\Za1iH valni 3 ^ fir** *fi* nr *8* 

V emu VtUUCJ (U C KJ Ul KJ . 


LabelRecoveiyRequest/ 

LabelSpecification/ 

LabelStockSize/Width 


Yes/ 
One 


#PCDATA 


1..3 


Height of the label image. For 
IN, use whole inches. 
For EPL2 labels only. 
Only valid value is *4\ 


LabelRecoveiyRequest/ 
TrackingNumber 


Cond/ 
One 


#PCDATA 


18 


Package Tracking number. 
If the TrackingNumber is not 
populated then the 
ReferenceNumber/V alue and 
the ShipperNumber 


LabelRecoveiyRequest/ 
ReferenceNumbei/V alue 


Cond/ 
One 


#PCDATA 


1..35 


Required if TrackingNumber is 
not populated. 

Customer supplied reference 
number. 

Supports up to 2 customer 
supplied combinations of 
ixeierence coae- vaiue 
combinations. 


LabelRecoveiyRequest/ 
ShipperNumber 


Cond/ 
One 


#PCDATA 


6 


Required if Reference Number/ 
Value is populated. 
Shipper's six digit account 
number. 

Must be six alphanumeric 
characters. 

Must be associated with the 
Internet account used to login. 
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UPS ONLINE TOOLS 



Label Recovery Request Example 

Example 1 — Using the Tracking Number to create LabelRecoveryRequest document: 

<? xml version= M l . 0 M ?> 
<AccessRequest xml : lang^'en-US" > 

<AccessLicenseNumber>5B531C246578B520</AccessLicenseNumber> 
<UserId>jef f york</UserId> 
<Password>Ship2A5</Password> 
</AccessRequest> 
<? xml version="1.0"> 
<LabelRecoveryRequest> 
<Request> 

<TransactionRef erence> 

<XpciVersion Version = M 1.0002 M /> 
</TransactionRef erence> 

<RequestAction>LabelRecovery</RequestAction> 
</Request> 

<LabelSpecif ication> 

<LabelPrintMethod> 

< Code >GI F< /Code > 
< /LabelPr intMethod> 
<LabelImageFormat> 

< Code >G I F< / Code > 
< /Label Image Format > 

</LabelSpecif ication> 

<TrackingNumber>lZE0E0970190020215</TrackingNumber> 
< /Label Recovery Re que st > 

Example 2 — Using Reference Number and Shipper Number to create LabelRecoveryRequest document: 

<? xml version="l . 0"?> 
<AccessRequest xml : lang^'en-US" > 

<AccessLicenseNumber>5B531C212348B520</AccessLicenseNumber> 
<UserId>XMLUser</UserId> 
< Pas s word>Ship2 A5 < / Pas sword> 
</AccessRequest> 
<? xml version="l . 0" > 
< Label Re coveryRequest> 
<Request> 

<TransactionRef erence> 

<XpciVersion Version = "1.0002"/> 
< /Transact ionRe ference > 

<RequestAction>LabelRecovery< /Request Act ion> 
</Request> 

<LabelSpecif ication> 

<LabelPrintMethod> 

<Code>GIF</Code> 

</LabelPrintMethod> 

< Label Image Forma t> 

< Code >GI F< / Code > 

< / Label Image Format > 
</LabelSpecif ication> 
< Re f e r enc eNumbe r > 

<Value>abcdef< /Value > 
</Ref erenceNumber> 

<ShipperNumber>abcl23</ShipperNumber> 
</LabelRecoveryRequest> 



C^B* United Parcel Service of America. Inc. AU Rights Reserved. Confidential and Proprietary 



Label Recovery Response Output 



DTD Definition 

< [ELEMENT LabelRecoveryResponse (Response , LabelResults*)> 
Table 5: Label Recovery Response Outputs 



Required/ 

Name (Xpath) Cardinality Type Length Description/Value 



LabelRecoveiyResponse/ 
Response/ 

TransactionReference/ 
CustomerContext 


No 


Any 


0..512 


Customer provided data. 
May be XML. If this data is 
present in the request, it is 
echoed back to the customer. 


LabelRecoveiyResponse/ 
Response/ 

Tran«nrtinnRp fp npnf***/ 

JL 1 at l^CXK, UU1 LI VC IC 1C1 IKAZI 

XPCIVersion 


No 


Alphanumenc 


1..50 


Identifies the version of the 
message . Current version is 
1.0002 


LabelRecoveiyResponse/ 
RespoiWResponseStatusCode 


Yes 


Numberic 


1 


Identifies the success or 
failure of the interchange. 
1 = Success 
0 = Failure 


LabelRecoveiyResponse/ 
Response/ 

ResponseStatusDescription 


No 


Alphanumeric 


1..15 


Describes the Response 
Status Code. 


LabelRecoveiyResponse/ 
Response/Error 


No 




Container 


If an error is encountered 
during the interchange, the 
Response contains an error. 
If the error is present, then 
the ErrorSe verity and 
ErrorCode are required. 


LabelRecove lyResponse/ 
Response/Erroi/ErrorSe verity 


Yes 


Alphanumeric 


1..15 


Describes the severity of the 
error. 


LabelRecove lyResponse/ 
Resporae/Eiroi/ErrorCode 


Yes 


Numberic 


1..15 


A numberic value that 
describes the error. Each 
tool defines a range of error 
codes. Refer to error 
conditions, in the 
appropriate chapter, for a 
complete list of interchange 
errors. 


LabelRecoveiyResponse/ 

Response/ErroiV 

ErrorDescription 


No 


Alphanumeric 


1..50 


Describes the error code. 
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Table 5: Label Recovery Response Outputs 



LabelRe cove ry Response/ 
Response/Error/ 
MinimumRetrySe conds 


NT 

No 


Numeric 


1 G 

1 ..3 


Number of seconds to wait 
until retry. This field is 
populated on special 
conditions of the Transient 
Error only, as defined by the 
service . 

A number between 1 and 
86400 (24 hours) 


LabelRecoveryResponse/ 
Res pons e/ErrorLocation 


No 




Container 


Identifies the element in 
error. 


LabelRecoveryResponse/ 
Response/ErrorLocation/ 
ErrorLocationElementName 


No 


Alphanumeric 


1..512 


The Xpath name of the 
element in error. This is a 
valid Xpath pointing to an 
element in the request 
document. 


LabelRecoveryResponse/ 
Response/ErrorLocation/ 
ErrorLocationAttributeName 


No 


Alphanumeric 


1..50 


The name of the attribute in 
error. This is the name of 
the attribute contained by the 
Error Location element 


LabelRecoveryResponse/ 
Response/ErrorLocation/ 


No 


Alphanumeric 


Bound by 
the size of 
the Request 
data. 


The contents of the element 
in error. 


LabelRecoveryResponse/ 
LabelResults 


No 

Zero to Many 




Container 


Information containing the 
results of the users Label 
Recovery Request. 


LabelRecoveryResponse/ 
LabelResults/TrackingNumber 


Yes 
One 


#PCDATA 


18 


Package Tracking number. 


LabelRecoveryResponse/ 
LabelSpecification/ 
LabellmageFormat/ Code 


Yes 
One 


#PCDATA 


3 


Code type that the label 
image is to be generated in. 
Valid value returned is GIF 


LabelRecoveryResponse/ 
Labellmage/ Graphiclmage 


Yes 
One 


Base 64 
Encoded 


Variable 
Length 


Base 64 encoded graphic 
image. 


LabelRecoveryResponse/ 
Labellmage/HTMLImage 


Cond 
One 


Base 64 
Encoded 


Variable 
Length 


Base 64 encoded html 
browser image rendering 
software. 

This is only returned for gif 
image formats. 
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Returns on the Web 



Label Recovery Response Example 

<? xml version^" 1 . 0" > 
<LabelRecoveryResponse> 
<Response> 

<TransactionRef erence> 

<XpciVersion Version = "1.0002"/> 
< /TransactionRef erence> 

<ResponseStatusCode>l</ResponseStatusCode> 

<ResponseStatusDescription>Success</ResponseStatusDescription> 
</Response> 
<LabelResults> 

<TrackingNumber>lZEOE0970190020215</TrackingNumber> 
< Label Image > 

< Label ImageFormat> 

<Code >GI F< /Code > 
< /Label Image Format > 

<GraphicImage>FSDJHSDJHJ3487EHNE9U8DY9VHRFV8 9SDFHFSDJHFSDIDFHSJKDFS JKDFSJIU9GFIUGJIFDUJG9U 
KGLD J FD KJDGK JD F KGD J LD F KS JGKD F JDKGFDG 9 E 0 ER I JGE 3 91 WURE 9 U 9 ER 0 UW 9 R 0 UR 9 W EGU 9 URE 9 WGUW 9 OU 9 0 GRUG 9 0 
GERUG9REUGWERGJIOJGIODFGUIOFDUGIOFUIGRUE090U9TERUT90RUT9EU90ERUT9ERU9EUER9TUT9R0UTE90RU9TE 
RU9 0RTEU9SDKHG JHGDFU< /Graphi c Image > 

<HTMLImage>SKJJKLHGIGKHGKJHGFJGFJHDFJGHDDJFHFDJHFJHFJKDHJKFDHJFJDFHDFJHJDFHGJDHGDFSHJKFSDH 
SDFJHFJSDHJKDFHFJKSHDSKJHGFDJS JDFSK^ 

HDF JH JDFHG JDHGDFSH JKFSDHSDF JHF JSDH JKDFHF JKSHDSKJHGFD JS JDFSKHGJKDS< / HTMLImage > 
</ Label Image > 
</LabelResults> 

</LabelRecoveryResponse> 



Returns on the Web Error Conditions 

Several errors can be encountered during the processing of Returns requests. Some errors are high in severity 
while others serve as warnings. The errors numbers are classified according to the table below. 



Table 6: Error Code Range 



Error Code 


Description 


Olxxxx 


XML error. 


02xxxx 


Architecture error. 


15xxxx 


Tracking-specific error. 



There are three levels of errors: 

• Hard Error — Hard Errors represent the highest level of severity and signify that the entire XML 
request is invalid. Data modifications must be made to the document prior to re-sending. Possible 
causes of Hard Errors are XML format discrepancies, missing XML elements, invalid data, etc. 

• Transient Error — Transient Errors may be recoverable when the XML request is re-sent. Data 
modifications are not necessary, but the XML request must be re-sent for attempted processing. 
Causes of Transient Errors include server connectivity or availability outages, database failure, system 
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timeout, etc. Transient Errors are accompanied by a Minimum Retry Seconds element that specifies 
the duration of time required before the request can be re-sent. 

Warning — Warnings represent die lowest severity and are stated even though processing will continue. 

When an error is encountered, it may affect multiple data elements. The user should inspect the Error/ 
Em3rlxDcation/EirorIx)cationElementName element included in the error to determine the name of the invalid 
element. 

The error code can be found in the <Response > container which is part of every document returned by UPS 
OnLine XML Tools. The <ResponseStatusCode> will contain the error code and the 
<ResponseStatusDescription> will contain the natural language description. 

<Response> 

<TransactionRef erence> 

<CustomerContext>AddressValidation</CustomerContext> 
<Xpci Vers ion >1 . 0001</XpciVersion> 
< /Transact ionRef erence> 

<ResponseStatusCode>l< /Responses tatusCode> 

<ResponseStatusDescription>Success</ResponseStatusDescription> 
< /Response > 

Table 7: Returns on the Web Request/Response Error Conditions 



Error Code Error Severity Description 



10001 


Hard 


The XML document is not well formed 


10002 


Hard 


The XML document is well formed but the 
document is not valid 


120001 


Transient 


XML Shipping System is unavailable. 


120002 


Transient 


Label generation unavailable. 


120003 


Transient 


Unable to generate label. 


120004 


Transient 


Unable to generate label html. 


120005 


Transient 


UPS Internet Membership Services system is 
temporarily unavailable 


120006 


Transient 


UPS Internet Membership Services system is 
temporarily unavailable 


120010 


Transient 


Rating System is temporarily unavailable 


120011 


Transient 


On Call Air Pickup system is temporarily 
unavailable 


120012 


Transient 


Unable to validate the shipment 


120020 


Hard 


Max packages per shipment exceeded. 


120050 


Hard 


Illegal RequestAction 


120051 


Hard 


Illegal RequestOption 


120099 


Hard 


Validation Error: (Description) 


120100 


Hard 


Missing/invalid shipper number 
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Table 7: Returns on the Web Request/Response Error Conditions 



120101 


Hard 


Missing/Invalid shipper name 


120102 


Hard 


Missing/Invalid shipper address line 1 


120103 


Hard 


Invalid shipper address line 2 


120104 


Hard 


Invalid shipper address line 3 


120105 


Hard 


Missing/Illegal ShipperCity 




TT | 

Mara 


Missing/ illegal onipperotaterrovvyode 


120107 


Hard 


Missing/Illegal ShipperPostalG>de. (Description) 


120108 


Hard 


Missing/Illegal ShippeiVAddress/GjuntryCode 


120109 


Hard 


Missing/Illegal Shipper/PhoneNumber 


120110 


Hard 


Missing/Illegal Shipper/ AttentionName 


120111 


Hard 


Stopment/Srupper/EmailAddress cannot exceed 
a length of 50 characters 


120112 


Hard 


Shipment/Shipper/EmailAddre ss is an invalid 
format 




nam 


Shipper number must contain alphanumeric 
charaters only 


120114 


Hard 


Shipper/PhoneNumber/ 
StmctmedPhoneNumbei/PhoneExtension 
cannot exceed the length of 4 . 


120115 


Hard 


Shipper/PhoneNumber must be at least 1 0 
alphanumeric characters 


120116 


Hard 


Shipper/PhoneNumber/ 

Structure dPhoneNumbe r/ PhoneExtension must 
contain only numbers 


120117 


Hard 


Shipper/PhoneNumber/ 
StructuredPhoneNumber/ PhoneExtension is 

nnltr ^iT/railraVkln 5F ffu> drim-io** ic 1j"m"»2*to*1 in 1 1^ 
Ulliy cl Villi cl Lilt; U Lilt; allippcl lULdLcLI 111 UvJ, 

Puerto Rico or Canada 


120118 


Hard 


Shipper/PhoneNumber/ 
StructuredPhoneNumber/ PhoneExtension is 
only valid if a phone number is given 


120119 


Hard 


Shipper phone number and phone extension 
together cannot be more than 1 5 digits long 


120120 


Hard 


The country associated with Shipper/ 
Shippe rNumbe r must be the same as the 
shipments origin country 


120121 


Hard 


Shipper/ShipperNumber is not an active account 


120122 


Hard 


Cannot place a shipment with the shipper 
number given in Shipper/ShipperNumber 
because of its account type. 
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Table 7: Returns on the Web Request/Response Error Conditions 



120200 


Hani 


Missing/Illegal ShipTo/ CompanyName 


120201 


Hani 


Missing/Illegal ShipTo/AttentionName 


120202 


Hani 


Missing/Illegal ShipTo/Address/AddressLinel 


120203 


Hani 


Illegal ShipTo/Address/AddressLine2 




riaru 


Illegal ShipTo/ Address/ AddressLine3 


120205 


Hard 


Missing/Illegal ShipTo/Address/City 


120206 


Hand 


Missing/Illegal ShipTo/AddressStateProvCode 


120207 


Hand 


Missing/Illegal ShipTo/Address/PostalCode. 
(Description) 


120208 


Hani 


Missing/Illegal ShipTo/Address/CountryGxle 


120209 


Hani 


Missing/Illegal ShipTo/PhoneNumber 


120210 


Hani 


Shipment/ShipTo/EmailAddress cannot exceed 
a length of 50 characters 




naiu 


vjiuprnerii/ omp 1 0/ j_jnaii/\QQress is an lnvaiia 
format 


120212 


Hani 


ShipTo/Phone Numbe r/ 

Structure dPhoneNumber/ Phone Extension 

Cell 11 MJL CAtccU Lilt; IcIlHUl Ul 


120213 


Hani 


ShipTo/PhoneNumber must be at least 10 
alphanumeric characters 


120214 


Hard 


ShipTo/PhoneNumber/ 

StructuredPhone Number/ Phone Extension must 

LUl 1LCU1 1 \JlU.y 1 1U1 1 1 IJXZ 1 .1 


120215 


Hard 


NViii~» Trk/Pl"W"»r»oWt imKor/ 
vjllip L\Jl ± 1 HJl lt;l NUlllL/tJl/ 

StructuredPhone Number/ Phone Extension is 
only available if the shipper is located in US, 
Puerto Rico or Canada 


120216 


Hard 


ShipTo/PhoneNumber/ 

OH UL LLU c Ul 1 1UI «J 1 ^ Ul I lUxz 17 I IlOlle J_*A.lJel IblOll 12» 

only valid if a phone number is given 


120217 


Hani 


ShipTo phone number and phone extension 
together cannot be more than 1 5 digits long 


120300 


Hani 


Missing/Illegal ShipFrom/ CompanyName 


120301 


Hani 


Missing/Illegal ShipFrom/AttentionName 


120302 


Hani 


Missing/Illegal ShipFrom/Address/ Address Line 1 


120303 


Hani 


Dlegal ShipFrom/Address/AddressLine2 


120304 


Hani 


Illegal ShipFrom/Address/AddressLine3 


120305 


Hani 


Missing/Illegal ShipFrom/Address/City 
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Table 7: Returns on the Web Request/Response Error Conditions 



120306 


Hard 


Missing/Illegal ShipFrom/Address/ 
State Pro vCode 


120307 


Hard 


Missing/Illegal ShipFromPostalCode. 
(Description) 


120308 


Hard 


Missing/Illegal ShipFrom/Address/CountryCode 


120309 


Hard 


Missing/Illegal ShipFrom/PhoneNumber 


120310 


Hard 


Shipment/ShipFrom/ EmailAddress cannot 
exceed a length of 50 characters 




riaru 


AinmmAtif/AlifnHtvMvi/ H mill A rl/ifttCC ic « 1 i r\ 

orupme nu onipr ron v CjniaiiM.acire5»5> ii an nivalin 
format 


120312 


Hard 


ShipFrom/PhoneNumber/ 
StructuredPhoneNumber/ PhoneExtension 
cannot exceed the length of 4 . 


120313 


Hard 


ShipFrom/PhoneNumber must be at least 1 0 
alphanumeric characters 


120314 


Hard 


ShipFrom/Phone Numbe r/ 

StructuredPhoneNumber/ PhoneExtension must 
contain only numbers 


120315 


Hard 


SriipFrom/Phone Number/ 

ourucurreax noneiNumDen jrnonei_*xierision is 
only available if the shipper is located in US, 
Puerto Rico or Canada 


120316 


Hard 


ShipFrom/Phone Numbe r/ 
StructuredPhoneNumber/ PhoneExtension is 
only valid if a phone number is given 


120317 


Hard 


The ShipFrom country must be the same as the 
Shipper country 


120318 


Hard 


ShipFrom phone number and phone extension 
together cannot be more than 1 5 digits long 


120400 


Hard 


The shipment is missing payment information. 


120401 


Hard 


Missing/Illegal Payme ntuiformation/Pre paid/ 
BillShipper 


120402 


Hard 


Missing/Illegal Payme ntlnforrnation/Pre paid/ 
BillShipper/ Cre ditCardType 


120403 


Hard 


Missing/Illegal Payme ntlnfbrmation/Pre paid/ 
BillShippe rl CreditCardNumber 


120404 


Hard 


Missing/Illegal Payme ndnformation/Prepaid / 
BiUShippeiVCrecHtCard/ ExpirationDate 


120406 


Hard 


Mismatch Credit Card Tyrje/CreditCard/Number 
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120407 


Hard 


The credit card you have provided in 
Paymentlnfonnation/Prepaid/ BillShipper/ 
CreditCard has expired 


120408 


Haiti 


Missing BillShipper/ CreditCard/Type 


120409 


Hard 


Error validating backup credit card 


1 9ftvi 1 ft 


Hard 


One payment method allowed for 
Paymentlnformation/Prepaid/ BillShipper 


1 9ftvl 1 1 


riaru 


Paymentlnformation/Prepaid/ BillShipper/ 
CreditCard is not allowed for shipments whose 
origin is not US or Puerto Rico 




rlara 


Missing/Invalid Paymentlnformation/ Prepaid/ 
BillShipper/ AccountNumber 


120413 


Hard 


The shipper number Paymentlnformation/ 
Pre paid/BillShippe rl AccountNumber cannot be 
billed because the account in not active 


120414 


Hard 


Credit card authorization failed, contact your 
financial institution 


120415 


Hard 


PaymentLiformation/Prepaid/BiUSrdpr^ 
AccountNumber must be the same shipper 
number as Shipper/ShipperNumber 


120500 


Hard 


Missing/Illegal Service/Code 


120501 


Hard 


Invalid Shipment/ReferenceNumber/ Value 


120502 


Hard 


Invalid ShipmentServiceOptions/ InsuredValue/ 
MonetaryValue 


120503 


Hard 


Shipment/Description must not exceed the 
length of 35 characters 


120504 


Hard 


InvoiceLineTotal is not allowed for this shipment 


120505 


Hard 


Saturday Delivery Option cannot be used for this 
shipment 


120506 


Hard 


Invalid Shipment/ReferenceNumber/ Code 


120508 


Hard 


Missing/Invalid ShipmentServiceOptions/ 
On(^lAir/Pickup/RckupDate 


120509 


Hard 


Invalid Shipment/ ShipmentServiceOptions/ 
InsuredValue/MonetaryValue 


120510 


Hard 


Invalid/Missing ShipmentServiceOptions/ 
OnCallAir/RckupDe tails/ I^testPickupTime 
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Table 7: Returns on the Web Request/Response Error Conditions 



120511 


Hard 


Invalid ShipmentServiceOptions/ OnCallAir/ 
HckupDetails/HckupUate or invalid 
ShipmentServiceOptions/ OnCallAir/ 
PirkiirvDp tails/ EariipstRclainTinie or Invalid 
ShipmentServiceOptions/ OnCallAir/ 
PickupDe tails/ LatestPickupTime 


IlUJ 16 


Hard 
1 Lai U 


>hinTYinnt/l JocrnnHnn lc roni linprl fnr tfiic 

shipment. 


120513 


Hard 


The first Email Address used for Email 

Shinmont \\i i~\tif\c t i r\n ovrMkHc fTK> ffYIStYimi 1T1"I 
OI HUH It 1 11 1 NLJLLllL-CiLllJI I cALccUj UTC 1 1 IcLAH 1 1U1 1 1 

length of 50 characters. 


120514 


Hard 


Invalid format for first Email Address used for 

XLITlclll Ollipillt:! 11 INOUlCdUUIl 


120515 


Hard 


ShipmentServiceOptions/ ShipmentNotification/ 

J^VldJliVlC^oct^t:/ iVltilllU UliUIUL CACGGU UlC ICIIgUl 

of 1 50 characters 


120516 


Hard 


Hie first Email Address used for Email 

Mimmant r\Ir\#-ifir«:»1*Srkr» i« micci'no nr~ rnntninc 

oiupiiieiii lNouiicciuuii ia iiu^uig <ji i^uiiuhils 
invalid characters 


120517 


Hard 


The second Email Address used for Email 

Shinmpnt l\Ir»rifir k sirir*ri pypppHc trv* mnYitni im 

length of 50 characters 


120518 


Hard 


The format of the second Email Address entered 
in for* Email Shiranpnt Notification is invalid 


120519 


Hard 


Trip QprnnH Kmail AHHttpss pntprpd in for Email 
Shipment Notification is missing or contains 
invalid characters 


120520 


Hard 


For a shipment, the maximum number of Email 
Addresses allowed for Email Shipment 
Notifications is 2 


120521 


Hard 


For a shipment, the maximum number of 
Memos allowed for Email Shipment Notifications 
is 1 


120522 


Hard 


Invalid Shipment/ Al te mate De li ve ryTime 


120523 


Hard 


Shipment/Documents Only is invalid with the 
shipments orgin/destination pair 


120524 


Hard 


Package Pickup Request is not available with 
this shipment's service 


120525 


Hard 


AltemateDettveiyTime must be between (valid 
start time) and (valid end time) 


120526 


Hard 


InvoiceLineTotal/ MonetaryValue may not 
exceed the length of 8 
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120527 


Hand 


Cannot use multiple types of currency in a 
shipment 


120528 


Hard 


A Qhinmpnt fan Hpivp onlv one tvnp of 
UnitOfMeasurement for Dimensions 


120529 


Hard 


A shipment can have only one type of 
ijniiv/uvieaSuremeiiL io* d vveigiii 


120530 


Hard 


ShipmentServiceOptions/ OnCallAir/ 

Pi/* In irtTlAtoilc/ >t iito 1\ nnmTn lono+Kt rannnt 
■ ll tvi 11 11 Jt*^ll.xf OUllJclvLHJlILLL/ IdlgUl Cell 11 KJL 

exceed 8 characters 


ILUJJI 


oara 


orupmenioervicevypuoris/ \^nvy<iiirtji7 
RckupDe tails/ FloorlD length cannot exceed 3 
characters 


120532 


Hard 


ShipmentServiceOptions/ OnCallAir/ 
RckupDe tails/ Location length cannot exceed 
11 characters 


120533 


Hard 


ShipmentServiceOptions/ OnCallAir/ 
RckupDe tails/ EadiestTlmeReady is required 


120534 


Hard 


ShipmentServiceOptions/ OnCallAir/ 
RckupDe tails/ LatestTime Ready is required 


120535 


Hard 


ShipmentServiceOptions/ OnCallAir/ 
RckupDe tails/ Contacrlnfo/Name is required 


120536 


Hard 


ShipmentServiceOptions/ OnCallAir/ 
RckupDetails/Contactlnfo/ Phone Number is 
required 


120537 


Hard 


Invalid/Missing ShipmentServiceOptions/ 
OnCallAir/RckupDetails/ EariiestRckupTime 


120538 


Hard 


On Call Air Rckup Error, (further description is 
provided in XML) 


120539 


Hard 


InvoiceLineTotal/ MonetaryValue is required 
and must be a whole number 


120540 


Hard 


On Call Air Rckup is not available for this 
shipment 


120541 


Hard 


Shipment/ReferenceNumber is not allowed for 
this shipment 


120542 


Hard 


Package/Re fe re nceNumber is not allowed for 
this shipment 


120543 


Hard 


No more than 2 Shipment/ReferenceNumber 
can be given per shipment 


120544 


Hard 


No more than 2 Package/ReferenceNumber can 
be given per package 



' United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 



Table 7: Returns on the Web Request/Response Error Conditions 



120545 


Hard 


Shipment/Description is not valid with this 
shipment 


120546 


Hani 


(UOM Weight) is not a valid unit of 
measurement for weight. 


120547 


Hand 


(UOM Dimension) is not a valid unit of 
measurement for dimensions. 


120548 


Hard 


A shipment cannot have a KGS/EM or LBS/CM 
as its unit of measurements 


120600 


Hard 


Missing Package/PackageType/Code 


120601 


Hard 


Missing/Illegal Package/Package Weight/Weight 


120602 


Hard 


Missing/Illegal Combination of Package/ 
Dimensions 


120603 


Hard 


Illegal Package/Reference/Value 


120604 


Hard 


Illegal PackageServiceOptions /InsuredValue/ 
MonetaryValue 


120605 


Hard 


Mismatch PackageDimensions/ PackageType 


120606 


Hard 


Mismatch PackageDimensions/ PackageType/ 
Package Weight 


120607 


Hard 


Illegal Package/Reference/Code 


120608 


Hard 


Package/Package Weight/Weight is required 


120609 


Hard 


All Package Dimensions are required and each 
must be greater than 0 


X6UD1U 


nam 


Invalid Package ServiceOptions/COD/ 
CODAmount/MonetaryValue 


120611 


Hard 


PackageServiceOptions/ VerbalCorifirmation/ 
&>ntactInfo/Name cannot exceed a length of 35 


120612 


Hard 


PackageServiceOptions/ Vert>alConfirmation/ 
Contactlnfo/PhoneNumber cannot exceed the 
length of 1 5 


120613 


Hard 


PackageServiceOptions/ VerbalCorifirmation/ 
Contactlnfo/PhoneNumber must be at least 1 0 
alphanumeric characters 


120614 


Hard 


PackageServiceOptions/ VerbalCorifirmation/ 

fontactlnfo/PhoneNumber/ 

Structure dPhone Number/ Phone Extension 

cannot exceed the length of 4 


120615 


Hard 


PackageServiceOptions/ VerbalConfirmation/ 
Contactlnfo/PhoneNumber/ 
StructuredPhoneNumber/ Phone Extension must 
contain numbers only 



United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 



Table 7: Returns on the Web Request/Response Error Conditions 



120616 


Hard 


Package/Package Weight/Weight cannot exceed 
a length of 5 


120617 


Hard 


PackageServiceOptions/ InsuredValue/ 
Monetary Value cannot exceed a value of 999 


120618 


Hard 


PackageoerviceUptions/ VerbalLbnfirrnation/ 
Contactlnfo/Name/ is required for verbal 
confirmation of delivery 


120619 


Hard 


FackageoerviceUptioris/ VeroalLonfirmation/ 

I^^Titr»r , fTMfrt/Phr*rif>i\iiirrih<*i^ i« npnuinprl fr»r"vf»i+ia1 

V-AJI lutC LU UUv 1 IIUIlcilLUHUCl 13 ICl|UllcU lUl VClUtU 

confirmation of delivery 


120620 


Hard 


Package/Package Weight, Package/ 
Dimensional Weight, Package/ Ove rsize Package 
and Package/Dimensions do not apply to UPS 
Envelopes 


120621 


Hard 


PackageServiceOptions/InsuredValue/ 
MonetaryValue cannot be greater than 
(Monetary Amount) (Currency Code) 




Hard 


Package/Description is required 


120623 


Hard 


Invalid Package/Description 


120624 


Hard 


A Return Shipment can only have one package 


120625 


Hard 


Invalid/Missing Package/ReturnService/Code 


120626 


Hard 


Invalid PackageServiceOptions/COD/ 
CODFundsCode 


120627 


Hard 


Invalid PackageServiceOptions/COD/COE)Code 


120628 


Hard 


Invalid PackageServiceOptions/ EMailAction/ 
NotificationCode 


120629 


Hard 


Invalid PackageServiceOptions/LabelDelivery/ 
EMailMessage/EMailAddress 


120630 


Hard 


Invalid PackageServiceOptions/LabelDelivery/ 
EMailMessage/UndeliverableEMailAddress 


120631 


Hard 


Invalid PackageSeiMceOptions/I^belDelivery/ 
EMailMessage/Memo 


120632 


Hard 


Invalid PackageServdceOptions/LabelDelivery/ 
EMailMessage/Subject 


120633 


Hard 


Invalid ShipmentServiceOptions/Notification/ 
EMailMessage/FromEMailAddress 


120634 


Hard 


Invalid ShipmentServiceOptions/PNotification/ 
EMailMessage/EMailAddress 


120635 


Hard 


Invalid ShipmentService Options/Notification/ 
EMailMessage/UndeliverableEMailAddress 
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120636 


Hani 


Invalid ShipmentServiceOptions/Notification/ 
EMailMessage/Memo 


120637 


Hand 


Invalid ShipmentServiceOptioris/ Notification/ 
EMailMessage/Subject 


120638 


Hand 


Invalid PackageServiceOptions/Notification/ 
EMailMessage/ReplyToEMailAddress 


120639 


Hani 


Invalid PackageServiceOptions/Notification/ 
EMailMessage/EMailAddress [1 ] 


120640 


Hani 


Invalid PackageServiceOptions/Notification/ 
EMailMessage/EMailAddress [2 ] 


120641 


Hard 


Invalid PackageServiceOptions/Notification/ 
EMaiMessage/UndeliverableEMailAddress 


120642 


Hard 


Invalid PackageServiceOptions/Notification/ 
EMailMessage/Memo 


120643 


Hard 


Invalid PackageServiceOptions/Notification/ 
EMailMessage/Subject 


120644 


Hard 


PackageServiceOptions/ LabelDelivery is not 
valid with the shipment's return service type 


120645 


Hard 


ShipmentServiceOptions/ Notification is not valid 
with the shipment's return service 


120646 


Hani 


Invalid PackageServiceOptions/ LabelDelivery/ 
EMailMessage/FromName 


120647 


Hard 


Invalid ShipmentServiceOptions/ Notification/ 
EMailMessage/FromName 


120648 


Hard 


Invalid PackageServiceOptions/Notification/ 
EMailMessage/FromName 


120649 


Hard 


Invalid ShipmentServiceOptions/ Notification/ 
NotificationCode 


120650 


Hani 


Invalid PackageServiceOptions/ Notification/ 
NotificationCode 


120700 


Hani 


Missing/Illegal LabelSpecification/ 
LabelPrintMethod/Code 


120701 


Hani 


Missing/Illegal LabelSpecification/ 
HTIPUserAgent 


120702 


Hard 


Missing/Illegal LabelSpecification/ 
Labellmage Format/ Code 


120703 


Hani 


Missing/Illegal Combination of 
LabelSpecification/ LabelStockSize 


120704 


Hard 


Missing/Invalid LabelSpecification/ 
LabelStockSize/Height 
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120705 


Hard 


Missing/Invalid LabelSpecification/ 
LabelStockSizeA/Vidth 


120801 


Hani 


Address Validation Error on Shipment/Shipper/ 
Address 


120802 


Hand 


Address Validation Error on Shipment/ShipTo/ 
Address 


120803 


Haiti 


Address Validation Error on Shipment/ 
ShipFrom/Address 


120804 


Warning 


Address Validation Warning on Shipment/ 
Shipper/Address. (Description) 


120805 


Warning 


Address Validation Warning on Shipment/ 
ShipTo/ Address. (Description) 


120806 


Warning 


Address Validation Warning on Shipment/ 
ShipFrom/Address (Description) 


121000 


Hard 


Hazardous Materials packages cannot weigh 
over 70 pounds. 


121005 


Hard 


The COD option cannot be combined with the 
Return Services option. 


121010 


Hard 


Hazardous materials cannot be shipped using 
the Return Services option. 


121015 


Hard 


The Saturday Delivery option cannot be 
combined with the Return Services option. 


121020 


Hard 


The Delivery Confirmation option cannot be 
combined with the Return Services option. 


121025 


Hard 


The maximum insured amount is $50,000. 


121030 


Hard 


Packages must weigh more than zero pounds. 


121031 


Hard 


Packages must weigh more than zero KG unit of 
measurement 


121035 


Hard 


The package weight cannot be greater than the 
service's max weight. 


121036 


Hard 


The value of Package/Package Weight/Weight 
cannot be greater than the service's max weight 
using KG unit of measurement 


121040 


Hard 


The Return Services accessories are unavailable 
with this service. 


121045 


Hard 


The Saturday Delivery option is unavailable with 
the given service. 


121047 


Hard 


Saturday Delivery may not be combined with a 
package type for the given product. 



United Parrel Service of America, Inc. AU Rights Reserved. Confidential and Proprietary 



Returns on the Web 



Table 7: Returns on the Web Request/Response Error Conditions 



121050 


Hard 


Package exceeds the maximum size total 
constraints of 130inches or 330 centimeters 
(length + girth, where girth is 2 * (width + 
height)). 


121055 


Hard 


This package exceeds the maximum length 
constraint of 108 inches. 


121056 


Hard 


Package/Dimensions/Length cannot exceed the 
max length of 270cm 


121057 


Hard 


The measurment system used is not valid for the 
shipFrom country 


121060 


Hard 


Hazardous materials cannot be shipped in a 
UPS Letter. 


121063 


Hard 


Accessorial cannot be shipped with the selected 
service. See digest for details. 


121065 


Hard 


Shipment of Hazardous Materials to the given 
destination is unavailable. 


121070 


Hard 


Accessorial is not allowed with certain 
access. methods. See digest for details. 


121075 


Hard 


The international declared value accessory is not 
valid with a domestic service. 


121080 


Hard 


The domestic declared value accessory is not 
valid with a international service. 


121085 


Hard 


The accessory cannot be added to the product 
See digest for details. 


i o i no c 


T T i 

Hard 


Only one Authorized Return Service option is 
allowed 


121087 


Hard 


The Authorized Return Service option is not 
allowed for shipments. 


121090 


Hard 


The package' s zone is invalid for the product 


121091 


Hard 


Extended area surchage is unavailable with this 
service. 


121095 


Hard 


A zone cannot be determined for the package 


121100 


Hard 


The selected service is invalid for the origin. 


121105 


Hard 


The given accessory key is invalid for the origin. 


121106 


Hard 


The specified country, origin or dest, is not 
supported. 


121107 


Hard 


A blank origin postal was specified. 


121108 


Hard 


Shipments must have at least 1 package. 


121109 


Hard 


The Delivery Area Surcharge Tier looked up is 
invalid 
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lei 1 1 U 


Hand 


lypically rndtcates a syntax error in the cfg file 


121115 


Hard 


The COD amount must be greater than zero 


121120 


Hard 


The COD amount cannot exceed $ 1 ,000 when a 
cashiers check or money order is requested. 


121125 


Hard 


The COD amount cannot exceed $50,000. 


121130 


Hard 


The Saturday Pickup option cannot be combined 
with the Return Services option. 


121135 


Hard 


The Saturday Pickup option cannot be combined 
with the Saturday Delivery option. 


121140 


Hard 


Saturday Pickup is unavailable with the selected 
service. 


121145 


Hard 


Only one Delivery Confirmation accessory is 
allowed per package. 


121150 


Hard 


Deliverv confirmation nnavnilahlf* with thp 

J^CllVClJr UUl 1111 11 luUUl 1 io tuiavcuiauic Willi UlC 

selected service. 


121155 


Hard 


The COD option is unavailable with the selected 

servicp and/ or* with thp ^hinmpnK nrloir*/ 

atl TIl^C UllUIUl W1UA UIC *31 U.LII 1 tXZ I ILO UllcllV 

destination pair. 


121160 


Hard 


The accessorv is invalid with thp hitlina ontinn 
See digest for details. 


121165 


Hard 


The Verbal Confirmation of Delivery option 
cannot be combined with the Return Services 
option. 


121170 


Hard 


The Delivery Confirmation option cannot be 
combined with the Verbal Confirmation of 
Delivery option. 


121175 


Hard 


Verbal Confirmation of Delivery is unavailable 
with the selected service. 


121180 


Hard 


Consignee Billing is unavailable with the selected 
service. 


121185 


Hard 


The selected service is unavailable to the desired 
country 


121190 


Hard 


Only one Return Services option is allowed. 


121195 


Hard 


The selected billing option is unavailable with 
the selected service. 


121196 


Hard 


The selected billing option is unavailable with 
UPS Letters. 


121198 


Hard 


The requested Hundredweight option is 
unavailable with UPS Letters 
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121200 


Hard 


Saturday Delivery is unavailable to desired 
destination. 


121205 


Hard 


Additional Handling is unavailable with the 
selected service. 


121206 


Hard 


Additional Handling is unavailable with UPS 
Letters. 


121210 


Hard 


The selected service is not available to the given 
destination. 


121211 


Hard 


Rating Error: (Description) 


121212 


Hard 


Package/PackagirigType/Code is invalid in a 
shipment from the origin to the destination 


121213 


Hard 


The billing option used in the shipment is 
unavailable in a from the origin to the 
destination 


121214 


Hard 


UPS cannot ship from the origin country to the 
destination country 


121215 


Hard 


The selected service is not available to 
residential destinations. 


121220 


Hard 


The Ship Notification option cannot be 
combined with the Return Services option. 


121225 


Hard 


Return Services are unavailable to the given 
destination. 


121230 


Hard 


Next Day Air Early AM Surcharge is unavailable 
with the selected service. 


121231 


Hard 


Switzerland Domestic Container must weigh 
greater than 2 KG 


121232 


Hard 


Worldwide Express Plus from Europe to 
Switzerland must be UPS Envelope or document 
only 


121233 


Hard 


Next Day Air Early AM is unavailable with the 
Hundredweight 


121235 


Hard 


No more than # of < accessory list> may 
be selected simultaneously. 


121240 


Hard 


Accessory name may not be applied more than # 
times. See digest for details. 


121245 


Hard 


Saturday Pickup and Shipper Duty Fees cannot 
be applied to the same package. 


121250 


Hard 


Saturday Delivery and Shipper Duty Fees cannot 
be applied to the same package. 


121255 


Hard 


Shipper Duty Fee is unavailable with the 
selected service. 
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121260 


Hard 


Shipper Duty Fee is unavailable with the 
selected billing option. 


121261 


Hard 


Accessory may not be combined with the 
product See digest for details. 


121262 


Hard 


Accessory may not be combined with the 
accessory. See digest for details. 


121265 


Hard 


The selected billing option is unavailable to the 
desired country. 


121266 


Hard 


The currency type used is not legal tender in the 
origin country 


121270 


Hard 


An invalid table or column name is used in 
SELECT.. WHERE 


121275 


Hard 


An error occurred adding a new rave attribute. 
See digest for details. 


121280 


Hard 


An error occurred removing a rave attribute. See 
digest for details. 


121285 


Hard 


The given postal code is invalid for the given 
state 


121286 


Hard 


The given state abbrev is invalid for the given 
country 


121290 


Hard 


The given billing option is invalid 


121295 


Hard 


A package of shipment has error. See digest for 
details. 


121300 


Hard 


Shipper Pays Duty - Tax Unpaid is unavailable 
with the selected accessorial. 


121305 


Hard 


Shipper Pays Duty - Tax Unpaid is unavailable 
with the selected service. 


121310 


Hard 


Shipper Pays Duty - Tax Unpaid is unavailable 
with the selected billing option. 


121315 


Hard 


The Authorized Return Service is unavailable 
with the selected accessorial. See digest for 
details. 


121320 


Hard 


The Authorized Return Service is unavailable 
with the selected service. 


121325 


Hard 


The Authorized Return Service is unavailable 
with the selected billing option. 


121330 


Hard 


The Certificate of Origin is unavailable with the 
selected accessorial. See digest for details. 


121335 


Hard 


The Certificate of Origin is unavailable with the 
selected service. 
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121340 


Hard 


The Certificate of Origin is unavailable with the 
selected billing option. 


121345 


Hard 


The Shipper Export Declaration is unavailable 
with the selected accessorial. See digest for 
details. 


121350 


Hard 


The Shipper Export Declaration is unavailable 
with the selected service. 


121355 


Hard 


The Shipper Export Declaration is unavailable 
with the selected billing option. 


121360 


Hard 


The Worldwide Express Plus Surcharge is 
unavailable with the selected service. 


121363 


Hard 


The One Time Pickup Surcharge is unavailable 
with the selected service. 


121365 


Hard 


Accessorial is not available with the selected 
access method. See digest for details. 


121370 


Hard 


Invalid access method. See digest for details. 


121375 


Hard 


Letter service is invalid for shipments with more 
than 1 package. 


121380 


Hard 


Package service does not match shipment 
service 


121385 


Hard 


Package billing option does not match shipment 
billing option 


121390 


Hard 


Package billing tier does not match shipment 
billing tier 


121395 


Hard 


Package consignee does not match shipment 
consignee 


121400 


Hard 


Package consignee street address line 1 does not 
match shipment consignee street address line 1 . 


121405 


Hard 


Package consignee street address line 2 does not 
match shipment consignee street address line 2 . 


121410 


Hard 


Package consignee street address line 3 does not 

mnl'pVl chinmont mncionao cfrnot aHHrocc lino -s 

uictu.il aiii|/iiieiiL consignee amid ciuuresa line o. 


121415 


Hard 


Package city does not match shipment city 


121420 


Hard 


Package state does not match shipment state 


121425 


Hard 


Package postal code does not match shipment 
postal code 


121430 


Hard 


Package country does not match shipment 
country 


121431 


Hard 


All packages in the shipment must have the 
same UPS Shipper Number. 
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121435 


Hard 


Ail packages in the shipment must have the 
Saturday Delivery option if 1 package has it 


121440 


Hard 


All packages in the shipment must have the 
Saturday Pickup option if 1 package has it 


121445 


Hard 


UPS does not allow Hazardous Materials in 
shipments consisting of more than one piece. 


121447 


Hani 


UPS does not allow Hazardous Materials in 
Hundredweight shipments 


121450 


Hard 


Only one type of Return Service option is 
allowed per package. 


121453 


Hard 


Hundredweight is not valid with Return Service 
options 


121455 


Hard 


All packages in the shipment must have the 
Return Services option if 1 package has it. 


121456 


Hard 


All packages in the shipment must have the 
Residential option if 1 package has it. 


121457 


Hard 


Shipments with the Residential option set must 
have the Residential option set on all packages. 


121460 


Hard 


Shipments cannot exceed a COD amount of 
$5,000 when requesting a cashiers check or 
money order. 


121465 


Hard 


Package access method does not match the 

iJlUUlllClll uvLCjj UlCUlVAli 


121470 


V Y CU. M. UI U£ 
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details. 


121500 


Hard 


Special rates are unavailable for the selected 
servirp iisinc thp splppfpri narkapp tvnp<j 


121501 


Hard 


Rating Error: (Description) 


i o 1 cm 


IT « 

Hard 


Unsupported package type type. 


121511 


Hard 


Unsupported accessory type 


121512 


Hard 


Unsupported billing option 


121513 


Hard 


Unsupported option 


121515 


Warning 


Weight of (actual weight) exceeds maximum for 
rating the requested container. Using standard 
package rates. 


121519 


Hard 


Package rating category does not match the 
shipment rating category. 


122000 


Hard 


Do not allow both oversize 1 and oversize 2 on 
the same package. 


123005 


Warning 


(Description) 
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123010 


Warning 


Package (s) in this shipment contains a warning: 
(Description) 


123020 


Warning 


The shipment's origin postal code given in 
ShipFrom/ Address/PostalCode is an invalid 
postal code for the origin 


123021 


Warning 


The shipment' s destination postal code given in 
ShipTo/ Address/PostalCode is an invalid postal 
code for the destination 


125000 


Hard 


Missing or invalid shipment digest. 


129000 


Warning 


Oversize 1 indicator has automatically been set 
on a Package. 


129001 


Warning 


Additional Handling has automatically been set 
on Package (index of the package). 


129002 


Warning 


An Extended Area surcharge of (monetary 
value) has been added to the service cost. 


129003 


Warning 


The requested service may not guarantee Next 
Day arrival to the selected location 


129004 




Check the UPS Service Guide for supported 
Saturday delivery destinations within the 
selected country 


129005 


Warning 


The requested service may not guarantee 
Second Day arrival to the selected location 


129006 




The Second Day Air service may not guarantee 
Second Day arrival to the selected location 


129007 


Warning 


Oversize 2 indicator has automatically been set 
on a Package 


129008 


Warning 


Weight is between 30 lbs and 69 lbs, oversize 1 
has automatically been set on a Package. 


129009 


Warning 


Oversize 1 does not apply, and has automatically 
been removed from a package. 


129010 


Warning 


Oversize2 does not apply, and has automatically 
been removed from a package. 


129011 


Hard 


The maximum insured value amount for the 1 - 
Attempt option is 999 USD 


129012 


Hard 


The maximum insured value amount for the 
Print and Mail option is 999 USD 


120913 


Hard 


The maximum insured value amount for the 
Print Return Label option is 999 USD 


120914 


Hard 


The maximum insured value amount for the 
Electronic Delivery option is 999 USD 
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120915 


Hani 


The maximum insured value amount for the 3- 
Attempt option is 999 USD 


20001 


Hard 


General process failure 


300001 


Hard 


Non-unique combination of shipper number and 
reference number - Candidate List returned 


300002 


Hard 


Return label for shipment already physically 
scanned 


300003 


Hard 


Return shipment can have only one package. 


Table 8: Void Error Conditions 


Error Code 


Error Severity 


Description 


190001 


Transient 


Void not available at this time. 


190002 


Transient 


Invalid/Missing registration ID. 


190030 


Hard 


XML is not well formed. 


190100 


Hard 


Invalid or missing 
ShipmentldentificationNumber. 


190101 


Hard 


Time for voiding has expired. 


190102 


Hard 


Multiple Shipments Found with Same Shipment 
ID or no shipment found. 
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1. Overview 

Starting with the Address Validation project it has become increasingly clear that XOLT needs to provide a 
consistent internal interface for its tools and components. Since many users outside of XOLT will come to 
depend on our components, every effort should be made to reduce coupling between us. Therefore, this 
interface's most salient feature lies in that the communication between the caller and component uses XML 
documents. As an additional benefit, this same interface may be employed throughout the XOLT suite 
with little expected change. 

The name is based on the nomenclature developed in the AV project: 

I 0 - The public XML interface. Accessible from the Internet, it includes the HTTP wrapper, the Licensing 
and Access XML document, and the XPCI Request/Response document. 

ly - The internal XML interface. Does not include the Licensing and Access XML document and may only 

be reached from inside the firewall. 

I 2 - Germane only to the AV project (so far). 



1 Basic Rules of the Game 

1. \ x . must be XPCI compliant and, if it exists, a proper subset of I 0 . This means Ii will be responsible for 
handling the XPCI Request and Response containers. 

2. For every i! interface there will be a DTD and/or schema describing the XML documents passed in 
and received in return although a validating parser will not be employed. 

3. The XML documents that are passed through a particular implementation of l x are the true nuts and 
bolts of the relationship between the caller and the component. The individual component technical 
specifications are responsible for detailing the XML document elements, structure, and related 
business rules. 

4. Changes to the XML documents passed back and forth through Ii should be backward compatible 
wherever possible. Alteration of the value of Pi (n) is the only legitimate excuse for breaking this rule. 

2 Assumptions 

The i! interface assumes 

a) The caller is in-process (if and until EJB's become a reality) 

b) The caller is written in Java 



3 Programmatic Interface 

The Ij interface is designed to pass in one or more XML documents in a single string and similarly return 
one or more XML documents. The Ii interface will, in order to prepare for the eventual adoption of EJB, 
will employ a factory style interface. 
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3.1 Class Name: <Component>Factory 

The factory constructs an <Component>Component object and returns it to the caller. The sole purpose of 
the factory is to hide the implementation details of the <Component>Component object. This allows the 
<Component> object to be distributed and scaled without the knowledge of the calling application. 



3.2 Constructor Summary 

none 

3.3 Public Methods 

< Component >Component get(); 

This method returns a component object instance to the caller. 

Void release (<Component>Component component) ; . 

This method returns the <Component>Component back to the <Component>Factory. Once the 
method call returns to the client, the client should not use the <Component>Component instance with 
first getting a new instance from the factory. 



3.4 Class Name: <Component>Component 

Constructor Summary 

< Component > Component < Component >Component ( ) ; 

This method constructs a component object. This method should not be called directly. The factory object 
should be used to construct the component. 

Public methods 

StringBuffer < Component >Request (String sRequesterlD, 

String sVersion, 
Hashtable processOptions, 
StringBuffer xml) ; 

This method will provide component services as detailed in the individual component documentation. 

sRequesterlD - the name of the requesting process. Examples: 
WWTNT 
Supply Ordering 

sVersion - The version identifier (e.g., "1.01") 

processOptions - This object is a hash table containing name/ value pairs of processOptions that are not 
contained in the XML. 

For example, a processOptions key/value that is necessary for certain Tools is HTTPContext. 

HTTPContext = key, HTTPContext = value -This HTTP Context object contains a hash table 
containing the name/ value pairs that come from the HTTP Session. If Ij is NOT called by an XML 
Tool, then the caller is responsible for setting up the following name/value pairs, should they be 
required by a specific implementation of l x : 
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xml<Component>Recruest - the component Request document as an XML string. Please see the 
DTD for details. 

The follow is an example of how to create the hash table and add an element: 



processOptions = new Hashtable ( ) ; 
processOptions . put. ( "HTTPContext" , 

newHttpContext ( ) . se tRemot eUser ( w ImsUser ID" ) ; 



Returns: 

The component response XML document as an XML string is returned. 



3.5 Errors, Warnings, and Exceptions 

The Ii implementation class is responsible for processing errors into the XPCI <Response> container and 
throwing an exception. Warnings will not result in a thrown exception. Two exceptions will be thrown, 
one for the XML 1.0 Standard related issues, the other for business issues: 

com.ups.olt.component.exceptions.OLTXMLException - the <Component>Component::request method 
cannot process the XML request document because: 

a) XML document is not well formed, 

b) XML document is not valid according to the relevant DTD (see below). 
com.ups.olt.component.exceptions.OLTBusinessProcessException - the underlying business logic has 
detected one or more errors. 

Both of the above classes will be derived from com.ups.oltxomponent.exceptions.OLTException and will 
contain the following: 

Appropriate XPCI response document - because the return value is not passed when an exception is 

thrown, this is required to provide I 0 classes with the correct XML response. 
Error Number - as assigned by the class implementing Ii. 
Error Severity - x = Hard, y = Transient , z= Whatever 

Error Description - l x will be responsible for supplying this description in the language in effect for the 
request object as specified by xmhlang (the default is en-US). 

The following URL gives the description of the usage of these classes 
http://xmldev2.ismd.ups.corn/Il/tree.html 



3.6 XML Validity 

The XML document passed in the <Component>Component:: request method must be valid according to a 
DTD that accompanies a particular component definition but the XML document must NOT include a 
<!DOCTYPE [root element] [...declarations...] > statement. Which is to say, the DTD should specify 
standalone=yes. 
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